@yahyahammad/venastine 0.3.8 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
@@ -1,1735 +1,1735 @@
1
- """
2
- core/compaction.py
3
-
4
- ROADMAP_v2 §21. Decides WHEN a thread should be compacted, WHAT may be
5
- folded, and runs the compactor agent to do it.
6
-
7
- The archive is never touched. Compaction adds a CompactionCheckpoint row
8
- and nothing else; storage.archive_history() keeps returning every message
9
- ever written, however many times this has run (§21 AC1). That is the property
10
- that makes an early, frequent trigger safe -- nothing is destroyed, only
11
- hidden from the next call.
12
-
13
- WHAT THIS MODULE OWNS
14
- should_compact() the trigger, in both its modes
15
- compactable_span() what may be folded, and the three floors that bound it
16
- compact() run the compactor, record the checkpoint, rebuild the view
17
-
18
- WHAT IT DOES NOT OWN
19
- Where the trigger is evaluated -- core/loop.py calls in, at a turn
20
- boundary and between steps. Assembling the derived view -- core/memory.py
21
- owns that, and compact() asks it to rebuild rather than splicing a
22
- summary in from here. Resolving settings -- core/config_loader.py's
23
- effective_compaction(), because it owns the merge and this module reaches
24
- agents.manager, which imports it.
25
-
26
- MEASUREMENT IS BY CHARACTERS, AND SAYS SO (M10). §21 asks for the summary's
27
- tokens to be counted; no tokenizer is available offline, and
28
- usage["input_tokens"] measures a whole prompt rather than a segment of one.
29
- Chars/4 applied to both sides of a ratio is self-consistent, which is all a
30
- ratio check needs -- it is never compared against a provider's count.
31
- """
32
-
33
- import json
34
- import logging
35
- import re
36
- import threading
37
- from typing import Optional
38
-
39
- import config
40
- from core import agent_activity, config_loader, model_windows, session
41
- from storage import THREAD_KIND_SUBAGENT
42
-
43
- logger = logging.getLogger(__name__)
44
-
45
- # M10. Rough and deliberately uncalibrated: it appears on both sides of
46
- # every comparison this module makes, so its accuracy cancels out. Never
47
- # compare a value derived from it against a provider's token count.
48
- CHARS_PER_TOKEN = 4
49
-
50
- # ROADMAP_v3 §81 (IM8). What one image weighs in that proxy, in tokens.
51
- #
52
- # A FIXED number, because the alternative is decoding every image to learn
53
- # its dimensions, which would take an imaging dependency this harness does
54
- # not carry. 1,600 is the top of Anthropic's own estimate (width x height /
55
- # 750, on an image it has already scaled to about 1.15 megapixels), so a
56
- # large image is counted at roughly its real cost and a small one is
57
- # overcounted. Overcounting folds a little early; undercounting would let a
58
- # thread of screenshots run past the window. Counting an image by its base64
59
- # LENGTH would be the third option, and the worst: a 1 MB file is about 1.3
60
- # million characters, which reads as 330,000 tokens and folds at once.
61
- IMAGE_TOKEN_ESTIMATE = 1600
62
- _IMAGE_CHARS = IMAGE_TOKEN_ESTIMATE * CHARS_PER_TOKEN
63
-
64
-
65
- def _image_count(images) -> int:
66
- """How many images one row or message carries (IM8): the decoded list on
67
- a neutral message, the JSON text `MessageLog.images` stores on an archive
68
- row, or nothing."""
69
- if not images:
70
- return 0
71
- if isinstance(images, str):
72
- try:
73
- images = json.loads(images)
74
- except ValueError:
75
- return 0
76
- return len(images) if isinstance(images, list) else 0
77
-
78
-
79
- def _row_chars(row) -> int:
80
- """One archive row's size in the proxy: its persisted content, plus IM8's
81
- fixed weight per image. EVERY row-size sum below goes through here, so a
82
- floor and the pin cap cannot disagree about what an image costs."""
83
- return len(row["content"]) + _image_count(row.get("images")) * _IMAGE_CHARS
84
-
85
- # The re-entrancy guard (M3). The compactor is an agent, so compacting runs
86
- # the loop, which evaluates the trigger, which could compact.
87
- #
88
- # PER THREAD SINCE BATCH 75, AND IT WAS A MODULE FLAG UNTIL THEN. That flag
89
- # said: "a thread-local would be more precise, but the loop is synchronous
90
- # and a compaction runs to completion before its caller resumes -- and a
91
- # module flag has the property that matters more: it is impossible to be
92
- # half-set." True when written, and §47's NA9 removed the premise. Two
93
- # children of one response each reach `_maybe_compact` on their own thread,
94
- # and a shared flag then does two wrong things:
95
- #
96
- # * the second child's `should_compact` returns "" and its compaction is
97
- # silently skipped for that step, because a sibling is mid-fold;
98
- # * whichever finishes first clears the flag while the other's compactor
99
- # is still running, reopening exactly the window this guard closes.
100
- #
101
- # Neither is loud: a skipped compaction self-corrects on the next step, so
102
- # the visible symptom would be a thread running into a provider's context
103
- # limit with a guard that looked like it was working. It was the seventh
104
- # member of slice 8's "six things that were only safe alone", found by
105
- # reading this comment against what NA9 had done to it.
106
- #
107
- # The half-set property survives, which is why this is still a flag and not
108
- # a lock: one bool per thread, set and cleared in a `finally` by the frame
109
- # that owns it. Nothing here serialises anything -- two conversations
110
- # folding at once is correct, since each needs its own fold.
111
- #
112
- # A FUNCTION RATHER THAN A BARE ATTRIBUTE, and the module name is GONE
113
- # rather than kept as an alias: `if _compacting:` against a callable is
114
- # always true, so a reader left holding the old name has to fail at import
115
- # instead of quietly disabling every compaction in the process.
116
- _reentrancy = threading.local()
117
-
118
-
119
- def _is_compacting() -> bool:
120
- """Whether THIS thread is already inside a compaction."""
121
- return getattr(_reentrancy, "active", False)
122
-
123
-
124
- def _set_compacting(active: bool) -> None:
125
- """Mark this thread as compacting, or done."""
126
- _reentrancy.active = bool(active)
127
-
128
-
129
- def _chars(messages) -> int:
130
- """Size of a neutral-shape message list, in characters."""
131
- total = 0
132
- for message in messages:
133
- total += len(str(message.get("content", "")))
134
- total += len(str(message.get("text", "")))
135
- total += _image_count(message.get("images")) * _IMAGE_CHARS
136
- for call in message.get("tool_calls", ()) or ():
137
- total += len(str(call))
138
- return total
139
-
140
-
141
- def estimated_tokens(messages) -> int:
142
- """A character-based estimate of what a message list will cost to send.
143
-
144
- Only used when nothing has been MEASURED yet -- a thread written before
145
- §21 existed, resumed for the first time. Every other evaluation reads
146
- memory.last_input_tokens, which is the provider's own count of exactly
147
- what it was sent and needs no estimate at all.
148
- """
149
- return _chars(messages) // CHARS_PER_TOKEN
150
-
151
-
152
- # Models already warned about, so the fallback notice is said once per
153
- # model rather than once per evaluation. Deduplicated on the MODEL, not
154
- # with a single boolean, for the same reason core/loop.py's
155
- # _headless_notices_shown keys on the hidden SET: a run that switches
156
- # model (or a pipeline whose critic model differs, §11) must still hear
157
- # about the second one.
158
- _context_window_warned: set = set()
159
-
160
- # The same once-per-model discipline for a DIFFERENT warning: a window so
161
- # small that the dependent floor leaves the trigger no usable headroom
162
- # (ROADMAP_v3 §65 A24). A separate set rather than a shared one, keyed on
163
- # the PAIR, because the two warnings answer different questions: the one
164
- # above is about a model missing from a table, which has no provider
165
- # dimension, while this one is about the number a provider REPORTED -- and
166
- # the same model name behind a gateway and behind its own vendor can report
167
- # different windows, so the pair is the thing that was warned about. Sharing
168
- # one set would also mean whichever fired first silenced the other.
169
- _floor_warned: set = set()
170
-
171
- # And a third, for the case A24 left out on purpose: the headroom CAP, not
172
- # the floor, leaves less room than one bounded read (TECHNICAL_DEBT 96,
173
- # batch 220). Its own set, keyed the same way and for the same reasons.
174
- _read_warned: set = set()
175
-
176
- # Threads whose turn count has already been reported as yielding (#217,
177
- # batch 221), so the INFO line is said once per thread. Keyed on the
178
- # THREAD, not the model: the condition is a property of the conversation.
179
- _yield_logged: set = set()
180
-
181
-
182
- # A trailing release date, as Anthropic and Google spell it.
183
- _DATE_SUFFIX = re.compile(r"-\d{8}$")
184
-
185
- # Region prefixes an inference gateway prepends, as an ALLOWLIST rather
186
- # than a dot-split. Two entries in the table -- `gpt-5.1` and
187
- # `qwen3.8-max-preview` -- contain dots inside the model name itself, so a
188
- # general "strip up to the first dot" rule would corrupt exactly the names
189
- # it was meant to preserve. Matching a known set cannot.
190
- _REGION_PREFIXES = ("us.", "eu.", "apac.", "us-gov.")
191
-
192
-
193
- def _normalized(model: str) -> str:
194
- """A model id reduced to the form MODEL_CONTEXT_WINDOWS is keyed in.
195
-
196
- LOOKUP ONLY. This never touches what is sent on the wire -- the model
197
- string the provider receives is always the one the caller supplied.
198
-
199
- Exact matching alone is why `claude-sonnet-5-20260724` used to resolve
200
- to the 200k default while `claude-sonnet-5` sat in the table at a
201
- million: a 5x undershoot that is silent after the first warning, and
202
- which reaches summarize_thread()'s truncation gate, not just the
203
- backstop. The table itself demonstrated the problem -- it keyed one
204
- Claude entry with a date suffix and five without.
205
-
206
- Deliberately narrow, and the rules only ever REMOVE a decoration that
207
- a gateway added:
208
-
209
- anthropic/claude-opus-5 -> claude-opus-5 (OpenRouter style)
210
- us.anthropic.claude-opus-5 -> claude-opus-5 (Bedrock style)
211
- claude-sonnet-5-20260724 -> claude-sonnet-5
212
- gpt-5.1 -> gpt-5.1 (untouched)
213
- qwen3.8-max-preview -> qwen3.8-max-preview
214
-
215
- An id that fits no rule is returned unchanged, so an unrecognised name
216
- still MISSES and still warns. That direction is deliberate: a loud
217
- miss costs an early compaction, a wrong prefix match costs a silently
218
- wrong window, and this table feeds a lossy truncation.
219
- """
220
- name = model.strip()
221
- if "/" in name:
222
- name = name.rsplit("/", 1)[-1]
223
- for prefix in _REGION_PREFIXES:
224
- if name.startswith(prefix):
225
- name = name[len(prefix):]
226
- break
227
- # Bedrock spells the vendor as a dotted segment after the region.
228
- if name.startswith("anthropic."):
229
- name = name[len("anthropic."):]
230
- return _DATE_SUFFIX.sub("", name)
231
-
232
-
233
- def context_limit(model: str, provider_name: Optional[str] = None) -> int:
234
- """The model's context window, for the pipeline backstop (M6).
235
-
236
- FOUR SOURCES, most local first:
237
-
238
- 0. A REMEMBERED override for this exact (provider, model) --
239
- core/model_windows.py, written by /window and kept across
240
- launches (batch 44). It wins because it is the one source a
241
- human set on purpose, and because the query it overrides can be
242
- confidently wrong: a gateway may report its own default rather
243
- than the deployment's, and a self-hosted endpoint's window is
244
- a fact only its operator has. Everywhere else in this project a
245
- measured value beats a configured one; here the direction is
246
- deliberately inverted.
247
- 1. What the provider SAID, via core.client.known_context_window --
248
- a cache-only read, primed by core/loop.py before every send. §21
249
- rejected querying on the belief that no provider in the roster
250
- could answer; re-measured, Anthropic reports max_input_tokens on
251
- the very ModelInfo the effort query already fetches, Google
252
- reports input_token_limit, and Groq/Mistral/Together/OpenRouter
253
- report a window under one of four field names. A queried answer
254
- also beats the table on a point the table cannot reach: it is
255
- what THIS account actually has, not what the model can have.
256
- 2. config.MODEL_CONTEXT_WINDOWS, normalized (see _normalized), which
257
- still answers for OpenAI, DeepSeek and Perplexity -- they report
258
- nothing, which is why §21's conclusion outlived its premise.
259
- 3. DEFAULT_CONTEXT_WINDOW, warned.
260
-
261
- Warned on fallback, per §21: a wrong-by-default window means the
262
- backstop fires at the wrong time in whichever direction the guess is
263
- wrong, and silent guessing turns a tuning problem into a mystery. Much
264
- less load-bearing than §21 assumed, though -- M1 moved the ordinary
265
- trigger off this table entirely, so a missing entry costs a mistimed
266
- backstop and a mistimed summarizer input budget rather than mistimed
267
- compaction.
268
-
269
- ONCE PER MODEL. This is called from thresholds(), which
270
- should_compact() calls on EVERY evaluation -- and _maybe_compact runs
271
- at the top of every step of every turn, so in a research run that is
272
- twice a step across ten passes. Unbounded repetition of a line the
273
- user can do nothing more about after reading it once is how a warning
274
- that matters gets trained past, and on the TUI it was also painting
275
- over the screen.
276
-
277
- `provider_name` is optional so that every existing caller keeps
278
- working; without it only sources 2 and 3 are available, which is
279
- exactly the behaviour that predated the query.
280
-
281
- THIS IS NOW ON EVERY THREAD'S PATH, not just a research pass's. Batch
282
- 44 made the working-set trigger a fraction of what this returns, so a
283
- wrong answer here no longer costs a mistimed backstop -- it decides
284
- when every chat compacts. That is why source 0 exists at the user tier
285
- and why the fallback below still warns.
286
- """
287
- override = model_windows.window_for(provider_name, model)
288
- if override:
289
- return override
290
-
291
- if provider_name:
292
- # Imported HERE, not at module scope. core/client.py defers its SDK
293
- # imports to keep `--help` fast (see its header), and this module is
294
- # reached from agents.manager, so a top-level import would both undo
295
- # that and add an import cycle. Guarded because a failure to read a
296
- # cache must never be the reason a thread cannot compact.
297
- try:
298
- from core import client as _client
299
-
300
- queried = _client.known_context_window(provider_name, model)
301
- except Exception: # pragma: no cover - defensive
302
- queried = None
303
- if queried:
304
- return queried
305
-
306
- window = config.MODEL_CONTEXT_WINDOWS.get(_normalized(model))
307
- if window is None:
308
- if model not in _context_window_warned:
309
- _context_window_warned.add(model)
310
- logger.warning(
311
- "No context window known for model %r%s; assuming %s. Set it "
312
- "with /window (remembered for this model) or add it to "
313
- "config.MODEL_CONTEXT_WINDOWS -- the compaction trigger, the "
314
- "research backstop and the summarizer's input budget all "
315
- "fire against this number.", model,
316
- f" on {provider_name}" if provider_name else "",
317
- config.DEFAULT_CONTEXT_WINDOW)
318
- return config.DEFAULT_CONTEXT_WINDOW
319
- return window
320
-
321
-
322
- def headroom_for(window: int) -> int:
323
- """Tokens held between the trigger and `window` -- a CLAMPED share.
324
-
325
- THE HEADROOM IS THE POINT, and batch 119 is where that got said out
326
- loud. The trigger's job is not to cap the thread at a tidy percentage;
327
- it is to leave room for the step that runs AFTER it fires, because
328
- nothing in this harness recovers from a prompt that overflows the
329
- window. There is no context_length_exceeded handler anywhere in
330
- core/ -- grep for one. The provider raises, core/loop.py retries the
331
- identical oversized prompt three times, and the turn dies. This number
332
- is the only thing standing between a thread and that.
333
-
334
- SO A BARE SHARE IS WRONG AT BOTH ENDS, which is the same shape of
335
- error batch 44 corrected in the other direction. Batch 44 replaced a
336
- flat 40k margin with a share because 40k is a rounding error under 1M
337
- and strangling under 64k; a bare share has the mirror-image defect,
338
- because what it holds CONSTANT is the percentage while the thing the
339
- headroom must contain -- one step's growth -- does not scale with the
340
- window at all. A single `max_read_chars` result is 12,500 proxy tokens
341
- whether the model holds 64k or a million. 0.10 of 1M is 100k, which is
342
- more than any step needs; 0.10 of 64k is 6,553, which one ordinary file
343
- read overflows.
344
-
345
- Hence a floor AND a cap, and each has a different job:
346
-
347
- * COMPACTION_MIN_HEADROOM_TOKENS keeps a small window usable. It
348
- binds under roughly 160k and nowhere above it, so a 262k or 1M
349
- thread gets the fraction exactly as configured.
350
- * COMPACTION_MAX_HEADROOM_FRACTION keeps the floor from eating a
351
- small window whole -- 16k of a 32k window is half of it -- and it
352
- is what keeps the resulting trigger positive at the bottom of the
353
- range.
354
-
355
- AND THAT IS NOT SUFFICIENT, which is TECHNICAL_DEBT 42 and the reason
356
- derived_trigger() now floors below. This bullet used to end "and above
357
- keep_recent_tokens at the bottom of the range, where
358
- effective_compaction() would otherwise raise" -- true, and it names
359
- ONE of the two dependent floors that function validates. The cap holds
360
- the trigger at 0.75*window down here, so it clears keep_recent_tokens
361
- (4,000) from a window of 5,334 up and clears warning_margin_tokens
362
- (8,000) only from 10,667 up. Measured: keep_recent_tokens never bites
363
- first anywhere in the range, which is exactly what made checking only
364
- it read as covered.
365
-
366
- MEASURED, not reasoned: the thread that produced this batch grew by
367
- 31,733 proxy tokens in ONE step (a single 117k-character arxiv_search
368
- result). At 0.85 its 262k window left 39,322 and that step fit; a bare
369
- 0.90 leaves 26,215 and it does not.
370
- """
371
- # `window - int(fraction * window)` rather than
372
- # `(1 - fraction) * window`, so the unclamped case reproduces the
373
- # fraction EXACTLY. The two differ by the truncation: 0.10 * 262144 is
374
- # 26214.4, and truncating the headroom down put the trigger one token
375
- # ABOVE int(0.90 * 262144). One token is harmless and an arithmetic
376
- # identity that holds only approximately is not -- every documented
377
- # table would be off by one with nothing to point at.
378
- share = window - int(config.COMPACTION_TRIGGER_FRACTION * window)
379
- floor = config.COMPACTION_MIN_HEADROOM_TOKENS
380
- cap = config.COMPACTION_MAX_HEADROOM_FRACTION * window
381
- return int(min(max(share, floor), cap))
382
-
383
-
384
- def _dependent_floor() -> int:
385
- """The smallest trigger effective_compaction() will accept.
386
-
387
- TECHNICAL_DEBT 42. That function validates the trigger against two
388
- settings of identical form -- `warning_margin_tokens` and
389
- `keep_recent_tokens`, each of which must be STRICTLY below it -- so the
390
- smallest acceptable trigger is one above the larger of the two.
391
-
392
- READ, NEVER HARDCODED, and that is the whole point of the helper. The
393
- numbers are 8,000 and 4,000 today; a literal 8,001 here would be
394
- correct until someone edited config.yaml:830, and then it would be a
395
- floor that no longer matches the validator it exists to satisfy. This
396
- reads the SAME resolution the validator reads, so the two cannot drift
397
- apart -- which is item 41's lesson applied to the fix and not only to
398
- the register entry.
399
-
400
- Bare, with no overrides, deliberately: a per-invocation
401
- `trigger_tokens` is the value being floored and must not decide its own
402
- floor, while the two margins resolve identically either way.
403
-
404
- COSTS ONE MERGE on should_compact()'s path. Measured: 3.267us against
405
- thresholds()'s 4.918us, so 66% of it in relative terms and 0.065ms per
406
- step of a research run in absolute ones -- against 4.696ms for one
407
- ordinary tool result's redaction pass. The relative figure is the one
408
- that looks alarming and the absolute figure is the one that is true.
409
-
410
- DEFENSIVE ABOUT ITS OWN READ. effective_compaction() cannot raise under
411
- config.yaml's 40,000 default, but a user settings.json naming a small
412
- `trigger_tokens` makes it raise on the way to telling us the margins --
413
- and derived_trigger() has callers outside thresholds(). A floor that
414
- cannot be computed must never become the reason a thread cannot
415
- compact, so this falls back to the config.py constants, which are the
416
- same numbers one tier down.
417
- """
418
- try:
419
- settings = config_loader.effective_compaction()
420
- margin = settings["warning_margin_tokens"]
421
- keep_recent = settings["keep_recent_tokens"]
422
- except Exception: # noqa: BLE001 -- see above
423
- margin = config.COMPACTION_WARNING_MARGIN_TOKENS
424
- keep_recent = config.COMPACTION_KEEP_RECENT_TOKENS
425
- return max(margin, keep_recent) + 1
426
-
427
-
428
- def _warn_if_the_floor_left_no_room(model: str, provider_name: Optional[str],
429
- window: int, share: int, floor: int,
430
- trigger: int) -> None:
431
- """Say ONCE, per (provider, model), that the floor is now the ceiling.
432
-
433
- TECHNICAL_DEBT 42 raised a floor under the derived trigger so that a
434
- small window could not make effective_compaction() raise on every
435
- turn. The floor is read from the same settings the validator reads, and
436
- it is applied WITH NO REFERENCE TO THE WINDOW -- so under the shipped
437
- 8,000/4,000 margins it is 8,001 whatever the model holds, and at or
438
- below 8,000 the trigger it produces is ABOVE the window. `used` is the
439
- provider's own count of what it was sent, so it can never reach a
440
- trigger above the window: compaction never fires, silently, and the
441
- only line the user sees is the warn branch's "approaching the
442
- compaction threshold", which collapses to warn_at == 1 down here and is
443
- therefore both constant and false.
444
-
445
- That is precisely the outcome item 42's own fix section rejected --
446
- "compaction would then silently never run on that model, which is the
447
- quiet-failure class this project keeps closing" -- arrived at from the
448
- other side. The floor stays, because the raise it removed was worse;
449
- what was missing is this line.
450
-
451
- FIRES ONLY WHERE THE FLOOR IS THE OPERATIVE VALUE, which is A24's
452
- ruling and is measured rather than guessed: the floor binds at or below
453
- a 10,666-token window and nowhere above it, because headroom's cap
454
- holds the share-derived trigger at 0.75*window down there. A window of
455
- 16,384 or 32,768 also leaves less headroom than one bounded read
456
- (12,500 proxy tokens), but the CAP is what bound it, the cap is
457
- deliberate (see headroom_for), and the only remedy there is a bigger
458
- model -- so a warning naming two settings would name the wrong thing.
459
- That case is TECHNICAL_DEBT 96, and since batch 220 it has a line of its
460
- own, `_warn_if_one_read_cannot_fit`, naming the read instead.
461
-
462
- Two wordings for one condition, because the remedy differs: at or above
463
- the window the trigger cannot be reached at all, and just below it the
464
- thread folds but the next step has almost nothing to grow into.
465
- """
466
- if floor < share:
467
- return
468
- one_read = int(config.MAX_READ_CHARS) // CHARS_PER_TOKEN
469
- if window - trigger >= one_read:
470
- return
471
- key = (provider_name or "", model)
472
- if key in _floor_warned:
473
- return
474
- _floor_warned.add(key)
475
- where = f" on {provider_name}" if provider_name else ""
476
- settings = (f"compaction.warning_margin_tokens "
477
- f"({config.COMPACTION_WARNING_MARGIN_TOKENS}) and "
478
- f"compaction.keep_recent_tokens "
479
- f"({config.COMPACTION_KEEP_RECENT_TOKENS})")
480
- if trigger >= window:
481
- logger.warning(
482
- "Compaction can NEVER fire for %r%s: its context window is %s "
483
- "tokens and the smallest trigger the settings allow is %s, which "
484
- "is above it. The thread will grow until the provider refuses "
485
- "the request. The floor is one token above the larger of %s -- "
486
- "lowering them lowers it.", model, where, window, trigger,
487
- settings)
488
- return
489
- logger.warning(
490
- "Compaction for %r%s can only fire with %s tokens of headroom left "
491
- "(window %s, trigger %s, held up by the floor rather than derived "
492
- "from the window): one bounded tool read is about %s proxy tokens, "
493
- "so the step after a fold can still overflow. The floor is one token "
494
- "above the larger of %s -- lowering them lowers it.",
495
- model, where, window - trigger, window, trigger, one_read, settings)
496
-
497
-
498
- def _warn_if_one_read_cannot_fit(model: str, provider_name: Optional[str],
499
- window: int, share: int, floor: int,
500
- trigger: int) -> None:
501
- """Say ONCE, per (provider, model), that one read can overflow the window.
502
-
503
- TECHNICAL_DEBT 96 (#246, batch 220): the case the warning above leaves
504
- out on purpose. On a 16,384- or 32,768-token window the floor does not
505
- bind; headroom_for's CAP does, and it leaves 4,096 or 8,192 tokens
506
- between the trigger and the window -- less than one bounded read's
507
- 12,500. A thread just under the trigger takes one large `read`, the
508
- prompt overflows, and nothing in core/ recovers from that.
509
-
510
- A24 was right that naming the two margins would name the wrong remedy.
511
- The right one is the READ: `max_read_chars` is a setting, and a value
512
- that fits the headroom keeps one read inside the window. The owner chose
513
- to say so over shrinking reads per model, which would need the window
514
- plumbed into every tool that reads the global. It applies to every
515
- model, and the line says that too.
516
- """
517
- if floor >= share:
518
- return # the floor binds; the warning above owns that case
519
- one_read = int(config.MAX_READ_CHARS) // CHARS_PER_TOKEN
520
- headroom = window - trigger
521
- if headroom >= one_read:
522
- return
523
- key = (provider_name or "", model)
524
- if key in _read_warned:
525
- return
526
- _read_warned.add(key)
527
- where = f" on {provider_name}" if provider_name else ""
528
- logger.warning(
529
- "Compaction for %r%s fires at %s tokens of a %s-token window, leaving "
530
- "%s tokens of headroom: less than one bounded tool read "
531
- "(max_read_chars is %s characters, about %s tokens), so one large "
532
- "read just below the trigger can overflow the window and end the "
533
- "turn. A max_read_chars of %s or less in config.yaml keeps a read "
534
- "inside it; it applies to every model.",
535
- model, where, trigger, window, headroom, config.MAX_READ_CHARS,
536
- one_read, headroom * CHARS_PER_TOKEN)
537
-
538
-
539
- def derived_trigger(model: str, provider_name: Optional[str] = None) -> int:
540
- """The working-set trigger for this model: its window less headroom.
541
-
542
- Batch 44's reversal of M1, as corrected by batch 119. The argument for
543
- deriving this from the window at all is on COMPACTION_TRIGGER_FRACTION;
544
- the argument for the clamps is on headroom_for() above.
545
-
546
- STILL NOT `window - margin`, which is the BACKSTOP's shape and is what
547
- batch 44 rejected: that is a FIXED margin, right at neither end of the
548
- roster. This is a share that may not shrink below an absolute nor grow
549
- past a share -- which is the same number at every window above ~160k
550
- and a floor below it.
551
-
552
- Floored at 1 rather than validated: context_limit() can only return a
553
- positive number, and effective_compaction() raises on a trigger below
554
- 1, so this exists to keep an absurd window from turning into a
555
- confusing error two layers away from the value that caused it.
556
-
557
- AND FLOORED AGAIN, above the dependent floors (TECHNICAL_DEBT 42).
558
- Headroom's cap holds the trigger at 0.75*window down here, so a window
559
- of 10,666 or less derives a trigger at or below warning_margin_tokens
560
- and effective_compaction() raises -- on should_compact()'s path, which
561
- runs at the top of every step, with both _maybe_compact call sites bare
562
- `yield from`. Every turn on such a model died before the first model
563
- call.
564
-
565
- REACHED BY A PROVIDER, NOT BY A COMMAND, which is what the register
566
- entry got wrong. /window refuses anything at or below the pipeline
567
- backstop margin (20,000), which is stricter than 10,666 and covers that
568
- route by coincidence; MODEL_CONTEXT_WINDOWS's smallest entry is 200,000
569
- and DEFAULT_CONTEXT_WINDOW is 256,000. Source 1 -- what the provider
570
- SAID -- has no guard at all, and 8,192 is the commonest real window a
571
- self-hosted or gateway endpoint reports.
572
-
573
- BELOW ~10,667 THIS STOPS BEING A DERIVATION, and that is said out loud
574
- rather than left to be discovered. The returned value is the floor, not
575
- 0.75*window, so the fraction no longer describes it. A derivation that
576
- silently stops deriving is the drift class this record is full of; the
577
- alternative was distrusting the provider's own number, which is a
578
- larger claim for a smaller gain.
579
-
580
- AND AT OR BELOW 8,000 IT STOPS BEING A TRIGGER, which is the step the
581
- paragraph above did not take (batch 148). The floor is applied
582
- with no reference to the window, so below itself it is simply larger
583
- than the window and nothing can reach it. Measured: a 4,096-token
584
- window derives 8,001 and should_compact() answers "warn" at every value
585
- from 1 to 4,097 and "compact" at none of them. The value is unchanged --
586
- _warn_if_the_floor_left_no_room above is the whole fix, because what was
587
- missing was never a number.
588
- """
589
- window = context_limit(model, provider_name)
590
- share = window - headroom_for(window)
591
- floor = _dependent_floor()
592
- trigger = max(1, share, floor)
593
- _warn_if_the_floor_left_no_room(model, provider_name, window, share,
594
- floor, trigger)
595
- _warn_if_one_read_cannot_fit(model, provider_name, window, share, floor,
596
- trigger)
597
- return trigger
598
-
599
-
600
- def _trigger_is_configured() -> bool:
601
- """Whether settings.json names compaction.trigger_tokens.
602
-
603
- The derived trigger is a DEFAULT, so it must not outrank a number a
604
- human wrote in a config file -- and effective_compaction() cannot tell
605
- a configured value from the config.py fallback, because it merges them
606
- into one dict by design (TECHNICAL_DEBT item 12: the merge records no
607
- provenance). Asking the settings directly is the narrow question this
608
- one decision needs, rather than a provenance mechanism the rest of
609
- that dict has done without.
610
- """
611
- return "trigger_tokens" in (config_loader.get_settings().get(
612
- "compaction") or {})
613
-
614
-
615
- def thresholds(model: str, mode: str = "working_set",
616
- overrides: Optional[dict] = None,
617
- provider_name: Optional[str] = None) -> tuple:
618
- """(warn_at, compact_at) in tokens, for this mode.
619
-
620
- TWO MODES, because a research pass and a chat turn want different
621
- answers (M6). "working_set" is the ordinary one: compaction keeps the
622
- thread inside a share of the model's window, so turns stay affordable
623
- and keep their tool steps. "backstop" is what a pipeline pass gets --
624
- it fires only just under the window, because a pass is headless and
625
- unattended and each one already returns a distillation, so routine
626
- compaction there would spend on a judgment call nobody is watching.
627
- Since batch 44 both are derived from context_limit(); what still
628
- separates them is how much room each leaves -- AND SINCE BATCH 148 the
629
- backstop is ordered against the trigger rather than merely given a
630
- bigger number, because "how much room each leaves" was answering the
631
- question backwards below 200,000 (batch 148).
632
-
633
- FOUR SOURCES FOR THE WORKING-SET TRIGGER, nearest first: an explicit
634
- `overrides` (a `/compact --strength N`), a session `/trigger` bound to
635
- this pair, settings.json's compaction.trigger_tokens, and the derived
636
- share. The first three are absolute numbers a human named and all
637
- outrank the derivation, which is what makes batch 44 a change of
638
- DEFAULT rather than a removal of the control.
639
- """
640
- # Resolved HERE because this is the only place the working-set trigger
641
- # is read and the only place that knows the model. effective_compaction
642
- # stays model-agnostic, and D27's four-tier chain is unchanged -- both
643
- # the session value and the derived default arrive through the existing
644
- # per-invocation slot rather than adding a fifth tier. An explicit
645
- # `overrides` still wins, since nearest is meant to win and the caller
646
- # is nearer.
647
- trigger = session.trigger_for(provider_name, model)
648
- if trigger is None and mode != "backstop" and not _trigger_is_configured():
649
- trigger = derived_trigger(model, provider_name)
650
- if trigger is not None:
651
- overrides = {"trigger_tokens": trigger, **(overrides or {})}
652
- settings = config_loader.effective_compaction(overrides)
653
- if mode == "backstop":
654
- # ABOVE THE WORKING-SET TRIGGER, STRUCTURALLY (batch 148).
655
- # "A last resort" is a statement about ORDER, and this was a flat
656
- # 20,000-token margin while batch 44 made the ordinary trigger a
657
- # clamped share -- so the backstop left MORE room than the trigger,
658
- # that is fired EARLIER, at every window below 200,000. Measured:
659
- # 4,000 tokens earlier at 64,000 and at 131,072, 11,808 earlier at
660
- # 32,768, and at or below 20,001 the old max(1, ...) clamped it to 1,
661
- # so every evaluation of every step of every pass asked compact().
662
- # M6's argument -- a pass is headless and unattended, so routine
663
- # compaction there spends on a judgment call nobody is watching --
664
- # was inverted for most of the roster.
665
- #
666
- # THE SHIPPED TABLE IS WHY NOTHING CAUGHT IT: every entry is at or
667
- # above 200,000, where the two numbers were equal or already in the
668
- # right order. The inversion is invisible on the table and universal
669
- # off it, and source 1 -- what a provider SAID -- is the way in.
670
- #
671
- # derived_trigger rather than the fully resolved working-set value:
672
- # it cannot raise (see its floor), and M6 speaks about the derived
673
- # default rather than about a number a human typed. A configured
674
- # trigger high enough to still invert this is one that is itself
675
- # near or above the window, and a reachable backstop under an
676
- # unreachable trigger is the right way round.
677
- compact_at = max(
678
- derived_trigger(model, provider_name) + 1,
679
- context_limit(model, provider_name)
680
- - config.COMPACTION_PIPELINE_BACKSTOP_TOKENS)
681
- return compact_at, compact_at
682
- compact_at = settings["trigger_tokens"]
683
- return compact_at - settings["warning_margin_tokens"], compact_at
684
-
685
-
686
- def should_compact(used: int, model: str, mode: str = "working_set",
687
- overrides: Optional[dict] = None,
688
- provider_name: Optional[str] = None) -> str:
689
- """"" | "warn" | "compact", from a measured context size.
690
-
691
- `used` is ModelResponse.usage["input_tokens"] from the most recent
692
- call -- the provider's own measurement of everything it was sent, which
693
- is exact but retrospective. That is why the check runs AFTER a response
694
- and acts before the next call.
695
-
696
- D21 is what makes this work rather than pedantry: a streaming path that
697
- silently reported zero usage would leave `used` at 0 forever, so
698
- compaction would never fire and the harness would run into a hard
699
- context-limit error from the provider instead. The budget stop
700
- condition and this trigger fail together, from the same cause.
701
- """
702
- if _is_compacting():
703
- return ""
704
- warn_at, compact_at = thresholds(model, mode, overrides, provider_name)
705
- if used >= compact_at:
706
- return "compact"
707
- if used >= warn_at:
708
- return "warn"
709
- return ""
710
-
711
-
712
- def _sub_turn_span(rows, starts, settings, current_turn_start):
713
- """A watermark INSIDE one turn, or None. Batch 120, register item 40.
714
-
715
- THE LAST RESORT, reached only when no turn-aligned fold exists at all.
716
- Batch 119 made the turn COUNT yield, which unsticks any thread with two
717
- completed turns; what it could not reach is a thread whose only turn is
718
- the one still running. The reported case was 142 rows and 168,311 proxy
719
- tokens inside ONE turn: over the trigger, entirely unfoldable, and
720
- answering `no-progress` on every evaluation forever.
721
-
722
- WHAT THIS AMENDS, PRECISELY. M5 says the current turn is never foldable
723
- because "a summary that swallowed the messages the model is reasoning
724
- about right now would rewrite the question mid-answer." The reason is
725
- right and it does not cover the whole turn: after forty-six steps the
726
- model is not reasoning about step three's tool output, and what must
727
- survive verbatim is the turn's own REQUEST plus the recent steps. Both
728
- do. The opening user row is re-added by `pinned_through` (see its
729
- docstring) and `keep_recent_tokens` of the tail is held back here, so
730
- the question is never rewritten -- it is carried unchanged, with the
731
- middle of the work folded between it and the recent steps.
732
-
733
- M4 IS SATISFIED BY CONSTRUCTION, not by checking. Its rule is that a
734
- fold must never separate an assistant message carrying `tool_calls`
735
- from the `tool_result` rows answering them, because a `tool_result`
736
- with no preceding `tool_use` is an HTTP 400 on Anthropic. Inside a turn
737
- the archive is `user, (assistant, tool+)*` -- D20 persists the
738
- assistant row before dispatch and the answering rows after it returns,
739
- including every row of a parallel dispatch -- so **cutting immediately
740
- before an assistant row leaves every earlier call answered.** Measured
741
- on the reported thread: 47 assistant rows inside the turn, 46 candidate
742
- boundaries, and 20 of its steps carry between 2 and 5 tool rows, which
743
- is exactly why the boundary is the assistant row and not an arbitrary
744
- position.
745
-
746
- Returns None rather than a boundary when the turn holds fewer than two
747
- steps. One step cannot be folded without folding all of it, and a turn
748
- with no steps is a bare request.
749
- """
750
- index = (current_turn_start if current_turn_start is not None
751
- else len(starts) - 1)
752
- if not 0 <= index < len(starts):
753
- return None
754
- opener = starts[index]
755
-
756
- steps = [i for i in range(opener + 1, len(rows))
757
- if rows[i]["role"] == "assistant"]
758
- if len(steps) < 2:
759
- return None
760
-
761
- # keep_recent_tokens of the tail, WHOLE STEPS at a time -- the same
762
- # floor and the same character proxy the turn-aligned path uses, just
763
- # counted over steps instead of turns, so the two cannot disagree about
764
- # how much verbatim tail a thread is promised.
765
- bounds = steps + [len(rows)]
766
- kept = 0
767
- cut = steps[-1]
768
- for position in range(len(steps) - 1, 0, -1):
769
- kept += sum(_row_chars(rows[i])
770
- for i in range(bounds[position], bounds[position + 1]))
771
- cut = steps[position]
772
- if kept // CHARS_PER_TOKEN >= settings["keep_recent_tokens"]:
773
- break
774
-
775
- # A BACKSTOP, and it is unreachable: the loop stops at `steps[1]` at the
776
- # earliest, so `cut` always exceeds `steps[0]` once there are two steps.
777
- # Kept rather than argued away, for `pinned_through`'s reason one file
778
- # over -- the failure it guards is a watermark that folds the request
779
- # and nothing else, which is the one outcome here that would be wrong
780
- # rather than merely unhelpful.
781
- if cut <= steps[0]:
782
- return None
783
- return rows[cut - 1]["id"]
784
-
785
-
786
- def compactable_span(memory, current_turn_start: Optional[int] = None,
787
- overrides: Optional[dict] = None):
788
- """The id of the last message that may be folded, or None if nothing
789
- may be.
790
-
791
- THREE FLOORS, AND THE EARLIEST WINS (M5) -- WITH ONE AMENDMENT, batch
792
- 119, argued in full at the `preferred` line below:
793
-
794
- * the current turn -- structural, never foldable at all. A summary
795
- that swallowed the messages the model is reasoning about right now
796
- would rewrite the question mid-answer. ABSOLUTE.
797
- * keep_recent_tokens, the token floor §21 specifies. ABSOLUTE, and
798
- it can be absolute safely because it is a SIZE: it holds exactly
799
- what it says and then stops.
800
- * the last N COMPLETED turns, verbatim. A single tool-heavy turn can
801
- consume the whole keep-token budget by itself, leaving the
802
- immediately preceding exchange summarized, and a follow-up like
803
- "no, the other one" then has no referent. A PREFERENCE SINCE BATCH
804
- 119: it is a COUNT, so it cannot tell three small turns from three
805
- enormous ones, and it applies only while it still leaves something
806
- foldable. Measured at 230k tokens held by `3 - 3 = 0` on a thread
807
- 92.5% of which could have been folded.
808
-
809
- So the guarantee this function makes is size-based rather than
810
- count-based: the current turn verbatim, plus at least
811
- keep_recent_tokens of completed turns verbatim, plus the last N
812
- completed turns whenever that is affordable.
813
-
814
- THE BOUNDARY IS ALWAYS A TURN START (M4). Every floor resolves to one,
815
- so a fold can never separate an assistant message carrying tool_calls
816
- from the tool results that answer them. That is not a quality concern:
817
- a tool_result with no preceding tool_use is an HTTP 400 on Anthropic --
818
- a hard wire error on the next call, on a thread that was working a
819
- moment ago.
820
-
821
- Returns None when the floors leave nothing, which is a real state and
822
- not a failure: a thread of three enormous turns is over the trigger and
823
- entirely protected. The caller reports it rather than silently doing
824
- nothing.
825
-
826
- EVERY FLOOR IS MEASURED IN ARCHIVE SPACE (M11), from one load of the
827
- thread's rows. The keep-tokens floor used to slice `memory.messages`
828
- and map positions back onto the archive's turn list; M8 puts a
829
- `role: "user"` summary at the head of a compacted view, so the two
830
- lists disagree by one turn and `current_turn_start` arrived in the
831
- wrong space entirely. That was §21a's shipped defect -- the watermark
832
- went backwards and the second compaction of a thread un-compacted it.
833
- Reading everything from `rows` makes the mismatch unrepresentable
834
- rather than merely fixed.
835
- """
836
- from storage import _ordered_rows
837
-
838
- settings = config_loader.effective_compaction(overrides)
839
- rows = _ordered_rows(memory.thread_id)
840
- starts = [i for i, row in enumerate(rows) if row["role"] == "user"]
841
- if not starts:
842
- return None
843
-
844
- # Every candidate boundary is "fold everything strictly before turn i".
845
- # The floors each veto some suffix of the turn list; the surviving
846
- # boundary is the earliest turn any of them still allows.
847
- #
848
- # The token floor: keep whole turns, walking back from the end, until
849
- # keep_recent_tokens is covered. Sized from the persisted content,
850
- # which is the same character proxy M10 uses everywhere else.
851
- bounds = starts + [len(rows)]
852
- kept = 0
853
- token_cutoff = len(starts)
854
- for index in range(len(starts) - 1, -1, -1):
855
- kept += sum(_row_chars(rows[i])
856
- for i in range(bounds[index], bounds[index + 1]))
857
- token_cutoff = index
858
- if kept // CHARS_PER_TOKEN >= settings["keep_recent_tokens"]:
859
- break
860
-
861
- # THE TWO FLOORS THAT CAN MEASURE WHAT THEY PROTECT, intersected first.
862
- cutoff = token_cutoff
863
- if current_turn_start is not None:
864
- cutoff = min(cutoff, current_turn_start)
865
-
866
- # ...and then keep_recent_turns, WHICH YIELDS RATHER THAN VETOES.
867
- # Batch 119, and this is an amendment to M5 rather than a fix to a
868
- # mistake in it.
869
- #
870
- # M5 names three floors and says the earliest wins. That is right for
871
- # two of them, because only two can measure what they are holding:
872
- #
873
- # * the current turn is STRUCTURAL -- folding it would rewrite the
874
- # question being answered -- and is never negotiable;
875
- # * keep_recent_tokens is a SIZE, so it protects exactly as much as
876
- # it says and then stops;
877
- # * keep_recent_turns is a COUNT, and a count is blind. Three turns
878
- # can be 2k tokens or 230k.
879
- #
880
- # Blind is harmless until the thread is over the trigger. Then it is
881
- # the one floor that can hold EVERYTHING while claiming to hold "the
882
- # last three exchanges" -- and at that point the alternative to folding
883
- # is not "keep the recent turns", it is the provider refusing the next
884
- # prompt. There is no context-overflow handler anywhere in core/, so
885
- # nothing downstream recovers.
886
- #
887
- # MEASURED, on the owner-reported thread that produced this batch: 182
888
- # rows, 729k chars, 230k tokens by the provider's own count, and
889
- # exactly THREE user turns. `3 - 3 = 0`, cutoff < 1, blocked -- while
890
- # the token floor on its own would have folded everything before turn 2:
891
- # 168,564 proxy tokens, 92.5% of the thread, with the last completed
892
- # turn and the current one untouched. A good fold existed and a turn
893
- # count vetoed it: on every evaluation, through a switch to a 1M-window
894
- # model (this function takes no model and never did), and through a
895
- # restart (it reads the archive, which does not change). There was no
896
- # way out of that state from inside the app.
897
- #
898
- # NOT A WALK-DOWN from 3 to 2 to 1 taking the first count that works.
899
- # On that same thread `keep_recent_turns=2` yields cutoff 1, which folds
900
- # turn 0's 253 tokens, writes a checkpoint, and then answers no-progress
901
- # forever -- a compaction that succeeds, frees 0.1%, and leaves
902
- # advances() permanently satisfied against a watermark that helped
903
- # nothing. Yielding all the way to the size-aware floors is what makes
904
- # the model call worth spending.
905
- #
906
- # Still guaranteed afterwards: the current turn verbatim, plus at least
907
- # keep_recent_tokens of completed turns verbatim. A size-based promise,
908
- # which is the right kind to make in answer to size pressure.
909
- preferred = min(cutoff, len(starts) - settings["keep_recent_turns"])
910
- if preferred >= 1:
911
- cutoff = preferred
912
- elif cutoff >= 1:
913
- # A STANDING CONDITION, said once per thread (batch 221, #217).
914
- # This runs once per compact(), which _maybe_compact calls after
915
- # every step while the thread is over the trigger -- so at INFO it
916
- # repeated per step for the life of the conversation, the shape #44
917
- # took out of this module. The first time a thread yields says it;
918
- # the rest are DEBUG, like the no-progress line that follows them.
919
- level = (logging.DEBUG if memory.thread_id in _yield_logged
920
- else logging.INFO)
921
- _yield_logged.add(memory.thread_id)
922
- logger.log(
923
- level,
924
- "Compaction on thread %s: keep_recent_turns=%d would have held "
925
- "all %d turns and blocked every fold, so it yielded. The current "
926
- "turn and keep_recent_tokens still hold.",
927
- memory.thread_id, settings["keep_recent_turns"], len(starts))
928
-
929
- # THE TURN-ALIGNED FOLD HAS TO BE WORTH A MODEL CALL, not merely legal.
930
- # Batch 134, and this is the gate `cutoff < 1` used to be.
931
- #
932
- # `completed_turns()` is `len(turn_start_ids) - 1`, so it is at least 1
933
- # for any thread with two user rows, and the token floor's loop assigns
934
- # `token_cutoff = index` BEFORE testing -- so it stops at
935
- # `len(starts) - 1` as soon as the last turn alone exceeds
936
- # keep_recent_tokens. Between them, `cutoff` was >= 1 on every thread
937
- # with a second user row, and the sub-turn path behind `cutoff < 1` was
938
- # unreachable there. The boundary was then the best TURN-ALIGNED one,
939
- # which on a thread whose current turn is almost all of it is the end of
940
- # the first turn.
941
- #
942
- # MEASURED on one 40-step turn, with and without one short exchange in
943
- # front of it:
944
- #
945
- # 40 steps, one user row SUB-TURN at row 73 folds 90.0%
946
- # one exchange, then the same turn-aligned row 2 folds 0.0%
947
- # two exchanges, then the same turn-aligned row 4 folds 0.1%
948
- # five exchanges, then the same turn-aligned row 6 folds 0.1%
949
- #
950
- # And it was a DEAD END rather than a slow start, because the useless
951
- # fold satisfies `advances()` permanently: every later evaluation
952
- # answered `no-progress`, at `logger.debug`, with `kind=None` so
953
- # `_maybe_compact` appended no notice -- nothing on screen while the
954
- # thread ran toward the provider's limit, where `headroom_for`'s
955
- # docstring says the loop retries the identical oversized prompt three
956
- # times and the turn dies. A sweep of every legal
957
- # keep_recent_tokens x keep_recent_turns pair reached a sub-turn
958
- # boundary 0 times in 30 accepted settings.
959
- #
960
- # This is the trap item 39 names and says it avoided -- "a successful
961
- # compaction that cannot be repeated" -- arriving on the DEFAULT
962
- # configuration with no settings edit at all, and item 40's own measured
963
- # scenario (two turns, 97.2% available) is the case the shipped gate
964
- # excluded.
965
- #
966
- # THE FLOOR IS keep_recent_tokens, which is the thing the fold exists to
967
- # make room behind: a boundary that frees less than the tail it must
968
- # keep has not answered the size pressure it was called for. Below it,
969
- # fall through to the sub-turn path exactly as `cutoff < 1` does -- and
970
- # that branch is kept untouched, so the single-turn case batch 120 fixed
971
- # is unchanged. `_sub_turn_span` itself needs nothing: with
972
- # `current_turn_start >= 1` it already resolves `opener = starts[index]`
973
- # to the current turn's user row and scans forward from there.
974
- worth_it = True
975
- if cutoff >= 1:
976
- freed = sum(_row_chars(rows[i])
977
- for i in range(starts[cutoff])) // CHARS_PER_TOKEN
978
- worth_it = freed >= settings["keep_recent_tokens"]
979
- if not worth_it:
980
- logger.info(
981
- "Compaction on thread %s: the turn-aligned boundary would "
982
- "free %d proxy tokens against a keep_recent_tokens of %d, "
983
- "which is not worth a model call, so the boundary is inside "
984
- "the current turn instead.",
985
- memory.thread_id, freed, settings["keep_recent_tokens"])
986
-
987
- if cutoff < 1 or not worth_it:
988
- # NO TURN-ALIGNED FOLD WORTH MAKING. Batch 120 tries one inside the
989
- # turn before giving up -- see _sub_turn_span for what that costs
990
- # and why M4 holds. Last, and only here: a turn-aligned boundary is
991
- # always preferable WHEN IT FREES ENOUGH, since it needs no row
992
- # re-added and no amendment to M5 at all.
993
- inside = _sub_turn_span(rows, starts, settings, current_turn_start)
994
- if inside is not None:
995
- if cutoff < 1:
996
- logger.info(
997
- "Compaction on thread %s: no turn-aligned fold exists "
998
- "(%d turns, all held), so the boundary is inside the "
999
- "current turn. Its request and the recent steps stay "
1000
- "verbatim.",
1001
- memory.thread_id, len(starts))
1002
- return inside
1003
- # A sub-turn fold is not available either (fewer than two steps in
1004
- # the current turn). A small turn-aligned fold still beats nothing,
1005
- # so fall back to it rather than refusing to compact at all.
1006
- if cutoff < 1:
1007
- return None
1008
- # Fold everything strictly before turn `cutoff`, so the watermark is
1009
- # the row just before that turn's first row. cutoff >= 1 guarantees
1010
- # there is one.
1011
- return rows[starts[cutoff] - 1]["id"]
1012
-
1013
-
1014
- def _target_chars(original_chars: int, strength: int) -> int:
1015
- return int(original_chars * config.COMPACTION_TARGET_RATIOS[strength])
1016
-
1017
-
1018
- def _instruction(segment_text: str, target: int, original: int) -> str:
1019
- return (
1020
- f"Summarize the conversation excerpt below.\n\n"
1021
- f"The original is {original} characters. Your summary must be at "
1022
- f"most {target} characters -- shorter is fine, longer will be "
1023
- f"rejected.\n\n"
1024
- f"--- BEGIN EXCERPT ---\n{segment_text}\n--- END EXCERPT ---"
1025
- )
1026
-
1027
-
1028
- def _as_text(messages) -> str:
1029
- lines = []
1030
- for message in messages:
1031
- role = message.get("role", "?")
1032
- if role == "assistant":
1033
- body = message.get("text", "")
1034
- calls = message.get("tool_calls") or []
1035
- if calls:
1036
- body = f"{body}\n[called: {', '.join(c.get('name', '?') for c in calls)}]"
1037
- else:
1038
- body = str(message.get("content", ""))
1039
- # ROADMAP_v3 §49 (SS5). A user-role row the HARNESS wrote -- a
1040
- # background session's result -- is not something the user said,
1041
- # and a summary that attributed program output to them would be
1042
- # M8's mistake one layer down.
1043
- if message.get("harness"):
1044
- role = "harness"
1045
- lines.append(f"{role}: {body}")
1046
- return "\n\n".join(lines)
1047
-
1048
-
1049
- def pin_measurements(thread_id, last_n: int, model: Optional[str] = None,
1050
- provider_name: Optional[str] = None) -> dict:
1051
- """What #89's cap is measured against, in M10's character proxy.
1052
-
1053
- Returns three numbers:
1054
- requested_tokens what the last `last_n` turns' ARCHIVE rows cost --
1055
- the span one more `pin(last_n)` would protect
1056
- pinned_tokens everything ALREADY pinned on this thread
1057
- max_tokens PIN_MAX_TRIGGER_FRACTION x the trigger that FIRES
1058
-
1059
- Reads the ARCHIVE (the same rows compactable_span walks), so a pinned
1060
- prefix is counted at full weight exactly as the derived view will
1061
- carry it. Never compared against a provider count (M10).
1062
-
1063
- THE PAIR IS OPTIONAL AND THE ANSWER DEPENDS ON IT (batch 148).
1064
- #89's cap is a fraction OF THE TRIGGER, and since batch 44 the trigger
1065
- that decides when a thread folds is derived per model -- so reading the
1066
- configured number alone made the cap 20,000 for every model and both
1067
- directions wrong. Measured against the trigger that actually fires:
1068
- 250% of it on an 8,192-token window, where one pin could protect more
1069
- than the whole trigger and floor the thread permanently above it, which
1070
- is the state #89 exists to prevent; and 8% of it on a 262,144-token
1071
- window, where `pin` refuses requests the stated policy allows. The
1072
- value was unchanged by batch 44 and the PROPERTY was not, which is the
1073
- marathon's shape 9, and AGENTS.md's "so #89's cap is unchanged" is the
1074
- sentence that made it look settled.
1075
-
1076
- The stated obstacle was real and is gone: this function had no
1077
- (provider, model) to match a session override against, and
1078
- `tools/builtin/pin.py` receives `parent_run` -- already in
1079
- registry._INJECTABLE_PARAMS, already carrying both -- one declared
1080
- parameter away. With the pair the trigger is resolved exactly as
1081
- thresholds() resolves it, so a session `/trigger`, a configured one and
1082
- the derivation all reach the cap through the chain that already exists.
1083
- Without it the binding-free read below is the fallback, so nothing that
1084
- calls this from outside a run moves.
1085
- """
1086
- from core import config_loader
1087
- from storage import _ordered_rows
1088
-
1089
- settings = config_loader.effective_compaction()
1090
- # THE MINIMUM, and the min() is load-bearing rather than defensive.
1091
- # With no (provider, model) to match a session override against, this
1092
- # reads the binding-free one -- and takes whichever trigger is SMALLER,
1093
- # which is safe under every binding. A raised session trigger leaves
1094
- # the cap stricter than it needs to be; a lowered one pulls the cap
1095
- # down with it. Reading the configured trigger alone would let
1096
- # `/trigger 12k` leave this cap at 20k, so a pin could protect more
1097
- # than the whole trigger and floor the thread permanently above it --
1098
- # which is the exact defect #89 exists to prevent, reintroduced
1099
- # through a number typed in a different command.
1100
- trigger = min(settings["trigger_tokens"],
1101
- session.trigger_any() or settings["trigger_tokens"])
1102
- if model:
1103
- try:
1104
- trigger = thresholds(model, provider_name=provider_name)[1]
1105
- except Exception: # noqa: BLE001 -- see below
1106
- # _dependent_floor's posture, for the same reason: a cap that
1107
- # cannot be computed must never become the reason a pin fails.
1108
- # effective_compaction raises on an incoherent settings.json,
1109
- # and the binding-free read above is still a cap.
1110
- logger.debug(
1111
- "Could not resolve the compaction trigger for %r on %r; "
1112
- "measuring the pin cap against the configured trigger.",
1113
- model, provider_name)
1114
- max_tokens = int(config.PIN_MAX_TRIGGER_FRACTION * trigger)
1115
-
1116
- rows = _ordered_rows(thread_id)
1117
- starts = [i for i, row in enumerate(rows) if row["role"] == "user"]
1118
- bounds = starts + [len(rows)]
1119
-
1120
- def _tokens(lo: int) -> int:
1121
- return sum(_row_chars(rows[i])
1122
- for i in range(lo, len(rows))) // CHARS_PER_TOKEN
1123
-
1124
- requested = _tokens(bounds[max(0, len(starts) - last_n)]) if starts else 0
1125
- pinned = sum(_row_chars(row) for row in rows
1126
- if row["pinned"]) // CHARS_PER_TOKEN
1127
- return {
1128
- "requested_tokens": requested,
1129
- "pinned_tokens": pinned,
1130
- "max_tokens": max_tokens,
1131
- }
1132
-
1133
-
1134
- def _truncate_oldest(text: str, budget: int) -> tuple:
1135
- """`(text, notice)` -- drop the earliest characters over `budget`.
1136
-
1137
- Returns the text unchanged and `None` when it already fits. The OLDEST
1138
- material goes, because recent turns are the referent-heavy ones, and
1139
- the cut is stated in the returned notice so both callers can put it in
1140
- the instruction AND in the stored row.
1141
-
1142
- ONE COPY, since batch 45. This was eight identical lines in `compact()`
1143
- and in `summarize_thread()`, notice string included, marked as
1144
- deliberate nowhere -- the shape
1145
- `safety/policy_enforcement.param_digest` calls this project's canonical
1146
- bug when it explains why the digest is not written twice. The two were
1147
- equivalent only by accident: the second guarded on a separate
1148
- `original` variable that happened to equal `len(thread_text)` at that
1149
- point, so the condition and the arithmetic under it could have drifted
1150
- apart without either copy looking wrong.
1151
- """
1152
- if len(text) // CHARS_PER_TOKEN <= budget:
1153
- return text, None
1154
- keep_chars = max(0, budget * CHARS_PER_TOKEN)
1155
- dropped = len(text) - keep_chars
1156
- notice = (f"[Source truncated: the earliest {dropped} characters were "
1157
- f"not summarized.]")
1158
- return f"{notice}\n{text[-keep_chars:]}", notice
1159
-
1160
-
1161
- def _input_budget(model: str, provider_name: Optional[str] = None) -> int:
1162
- """One-call INPUT ceiling for a summarizer prompt, in proxy tokens.
1163
-
1164
- context_limit minus the pipeline backstop margin -- generous by
1165
- construction, and honest about its weakness (M10): this compares the
1166
- chars-per-token PROXY against a real window number, which every other
1167
- comparison in this module refuses to do. The comparison is inherently
1168
- approximate; what makes it safe is the failure direction. Undershooting
1169
- the budget costs truncation, which is stated; overshooting it costs an
1170
- oversized send, which is a provider error mid-compaction on exactly
1171
- the thread that can least afford one.
1172
- """
1173
- return max(1_000, context_limit(model, provider_name)
1174
- - config.COMPACTION_PIPELINE_BACKSTOP_TOKENS)
1175
-
1176
-
1177
- def parse_compact_args(args: str) -> tuple:
1178
- """(overrides, error). ROADMAP_v2 §21's per-invocation override --
1179
- applies to this one run and persists nothing, which is the last step
1180
- of D27's resolution order.
1181
-
1182
- `/compact`'s grammar in either shell: both parse here, so one cannot
1183
- accept a spelling the other refuses (ROADMAP_v3 §89; moved from
1184
- tui/app.py).
1185
-
1186
- An unrecognised flag is an ERROR, not something to ignore. Silently
1187
- dropping `--strenght 4` would compact at the default strength while
1188
- the user believes they asked for something else, and the result looks
1189
- exactly like a compaction that obeyed them.
1190
- """
1191
- overrides: dict = {}
1192
- tokens = args.split()
1193
- index = 0
1194
- while index < len(tokens):
1195
- token = tokens[index]
1196
- if token in ("--strength", "-s"):
1197
- index += 1
1198
- if index >= len(tokens):
1199
- return None, "--strength needs a value from 1 to 5."
1200
- try:
1201
- overrides["strength"] = int(tokens[index])
1202
- except ValueError:
1203
- return None, f"--strength needs a number, got {tokens[index]!r}."
1204
- elif token.startswith("--strength="):
1205
- value = token.split("=", 1)[1]
1206
- try:
1207
- overrides["strength"] = int(value)
1208
- except ValueError:
1209
- return None, f"--strength needs a number, got {value!r}."
1210
- else:
1211
- return None, f"Unknown option {token!r}. Usage: /compact [--strength N]"
1212
- index += 1
1213
- return overrides, None
1214
-
1215
-
1216
- def compact(memory, model: str, provider_name: str,
1217
- current_turn_start: Optional[int] = None,
1218
- overrides: Optional[dict] = None,
1219
- authorization=None,
1220
- activity=None, depth: int = 1) -> dict:
1221
- """Compact `memory`'s thread. Returns an OUTCOME dict -- never None.
1222
-
1223
- Batch 16 (#44) changed this contract. It used to return a notice dict
1224
- on success and None on every other exit -- five flavors of "nothing
1225
- happened" that were indistinguishable at the call site and logged by
1226
- three different conventions (WARNING per evaluation, debug-only,
1227
- nothing at all). Now every exit is data:
1228
-
1229
- {"status": <one of the seven below>,
1230
- "kind": <notice kind for the loop's per-run dedup, or None>,
1231
- "text": <a human line both shells render>}
1232
-
1233
- The seven statuses, which are this function's whole vocabulary:
1234
-
1235
- folded a checkpoint was written (kind="compaction")
1236
- blocked the keep floors protect everything
1237
- all-pinned everything newly foldable is pinned (#89's silent
1238
- path, named now)
1239
- missing-agent the compactor definition is absent
1240
- no-progress the fold boundary has not moved past the last
1241
- checkpoint
1242
- reentrant a compaction is already running in this process
1243
- failed the compactor produced nothing usable
1244
-
1245
- Three of them are STANDING CONDITIONS (blocked, all-pinned,
1246
- missing-agent) and share one notice kind, so the loop's existing
1247
- once-per-run dedup governs their WARNINGs too instead of each firing
1248
- its own per-evaluation line. They are enumerated HERE, at the function
1249
- that produces them, rather than in a module-level tuple: batch 16 kept
1250
- a `COMPACTION_OUTCOMES` sequence beside this docstring and nothing ever
1251
- read it, which is `CODE_STAGES`' shape exactly (see the note in
1252
- core/reasoning/events.py) -- a list whose only future was drifting away
1253
- from the call sites while looking like a contract.
1254
-
1255
- REPORTABILITY LIVES WITH THE CALLER. How often this function runs --
1256
- once at the turn boundary plus once after every step -- is run-scope
1257
- knowledge the loop has and this module lacks, which is why the
1258
- standing-condition WARNINGs moved out of it into _maybe_compact's
1259
- once-per-run guard (#44). What remains here is mechanics: DEBUG for a
1260
- fold boundary that did not move, and _summarize's own retry warnings,
1261
- which are events about one model call rather than states of the run.
1262
-
1263
- Runs the compactor as an ORDINARY AGENT through the same
1264
- RunAgentLoop everything else uses. §21 is explicit that summarizing is
1265
- the shape of an agent call -- a system prompt, a task, a judgment-based
1266
- output -- and that routing it through the shared machinery is also what
1267
- gives it real autonomy over WHAT to preserve. Mechanical truncation
1268
- cannot exercise judgment at all.
1269
-
1270
- The compactor's own run gets its own fresh thread, no tools
1271
- (`allowed_tools: []` in its definition), and the re-entrancy guard, so
1272
- it can neither call anything nor trigger a compaction of its own.
1273
- """
1274
- from agents.manager import manager
1275
- from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop
1276
- from storage import (
1277
- advances,
1278
- history_through,
1279
- latest_checkpoint,
1280
- save_checkpoint,
1281
- )
1282
- storage_advances = advances
1283
-
1284
- if _is_compacting():
1285
- return {"status": "reentrant", "kind": None,
1286
- "text": "A compaction is already running."}
1287
-
1288
- settings = config_loader.effective_compaction(overrides)
1289
- watermark = compactable_span(memory, current_turn_start, overrides)
1290
- if watermark is None:
1291
- logger.debug(
1292
- "Compaction wanted on thread %s but every message is protected "
1293
- "by the keep floors; nothing folded.", memory.thread_id)
1294
- return {
1295
- "status": "blocked",
1296
- "kind": "compaction_blocked",
1297
- # TWO FALSE CLAIMS IN ONE LINE, both corrected in batch 119.
1298
- #
1299
- # "Context is full" -- it is not. The trigger is a fraction of
1300
- # the window, so this is read with the headroom still unspent,
1301
- # and the owner who reported it reasonably concluded the harness
1302
- # treats the window and the trigger as one number. The usage
1303
- # line showing the TRIGGER as its only denominator is the other
1304
- # half of that impression; batch 119 fixes both.
1305
- #
1306
- # "the most recent turns fill it entirely" -- names SIZE, and
1307
- # what actually blocked the one reported occurrence was a turn
1308
- # COUNT on a thread 92.5% of which was foldable. The single
1309
- # diagnostic this message offered pointed away from its cause,
1310
- # which is worse than offering none.
1311
- "text": ("Over the compaction trigger, but every turn is held "
1312
- "by the keep floors -- nothing could be folded. The "
1313
- "thread keeps running uncompacted; a fold becomes "
1314
- "possible once this turn completes."),
1315
- }
1316
-
1317
- agent = manager.get(config.COMPACTOR_AGENT)
1318
- if agent is None:
1319
- logger.debug(
1320
- "Compaction wanted but the %r agent is not available.",
1321
- config.COMPACTOR_AGENT)
1322
- return {
1323
- "status": "missing-agent",
1324
- "kind": "compaction_blocked",
1325
- "text": (f"The {config.COMPACTOR_AGENT!r} agent is not "
1326
- f"available, so this conversation cannot be "
1327
- f"condensed."),
1328
- }
1329
-
1330
- previous = latest_checkpoint(memory.thread_id)
1331
- # NO PROGRESS, NO CALL. A watermark at or before the existing one means
1332
- # the floors have not moved past what is already summarized -- there is
1333
- # nothing new to fold. Checked HERE rather than only in save_checkpoint
1334
- # because the model call happens in between: without it, rederive would
1335
- # re-summarize a span it has already summarized, and chain would be
1336
- # handed an empty segment and summarize its own previous summary,
1337
- # degrading it a little on every attempt. Both spend a real call to
1338
- # achieve nothing.
1339
- if previous is not None and not storage_advances(
1340
- memory.thread_id, previous["covers_up_to_message_id"], watermark):
1341
- logger.debug(
1342
- "Compaction wanted on thread %s but the fold boundary has not "
1343
- "moved past the last checkpoint; nothing to do.", memory.thread_id)
1344
- return {"status": "no-progress", "kind": None,
1345
- "text": "Nothing new to fold since the last summary."}
1346
-
1347
- # M2 as amended by batch 16 (#90). Re-derive from the archive by
1348
- # default WHEN CONFIGURED; chain summarizes the previous summary plus
1349
- # the tail. Whichever is configured, a span that outgrows one call
1350
- # falls back to chain (verbose -- see the WARNING below), and one that
1351
- # outgrows it even chained truncates its oldest material with the
1352
- # truncation stated twice: to the model in the instruction, and in the
1353
- # stored summary every later turn reads.
1354
- chaining = settings["strategy"] == "chain" and previous is not None
1355
-
1356
- def _build(chain_mode: bool):
1357
- lower = previous["covers_up_to_message_id"] if chain_mode else None
1358
- seg = history_through(memory.thread_id, watermark,
1359
- after_message_id=lower)
1360
- text = _as_text(seg)
1361
- if chain_mode:
1362
- text = ("Summary of everything before this point:\n"
1363
- f"{previous['summary_text']}\n\n{text}")
1364
- return seg, text
1365
-
1366
- segment, segment_text = _build(chaining)
1367
- if not segment:
1368
- # Everything newly foldable is pinned (#89). This used to be the
1369
- # one silent no-progress path -- indistinguishable, at every
1370
- # level, from "nothing needed doing" -- while the state it reports
1371
- # is exactly what compaction_blocked's text describes, reached by
1372
- # another door. Named now, and worded so the reader knows the way
1373
- # out.
1374
- #
1375
- # ON THE SEGMENT, NOT ON THE STRATEGY (batch 148). This
1376
- # read `if not segment and not chaining:` from the day it was
1377
- # written, and `chaining` is true under the SHIPPED
1378
- # `compaction_strategy: chain` whenever a checkpoint exists -- so
1379
- # the default strategy fell straight through the branch built for
1380
- # this state. What it fell into is the harm the no-progress guard
1381
- # twenty lines above names as its own reason: "chain would be
1382
- # handed an empty segment and summarize its own previous summary,
1383
- # degrading it a little on every attempt". That guard catches a
1384
- # watermark that has not MOVED; it cannot catch a watermark that
1385
- # moved across a region which is entirely pinned, because the
1386
- # boundary genuinely advanced. This branch is the guard for that
1387
- # case and the strategy test removed the default from its cover.
1388
- #
1389
- # Measured through the real compact() with three pinned turns in a
1390
- # ten-turn thread: the compactor was handed exactly
1391
- # "Summary of everything before this point:\n<previous summary>\n\n"
1392
- # and nothing else, at a 379-character target, and the stored
1393
- # checkpoint went from 2,489 characters to 23 -- reported as
1394
- # status="folded", kind="compaction", "0 earlier messages compacted
1395
- # into a summary". A success line for a durable 99% loss, and it
1396
- # compounds geometrically on every repeat.
1397
- #
1398
- # EMPTY MEANS PINNED, exactly: history_through excludes pinned rows
1399
- # (§21 AC2) and excludes nothing else, so an empty segment on a
1400
- # watermark that advanced is this state and no other. The message
1401
- # is therefore as true under chain as under rederive, and an
1402
- # explicit /compact is refused here for the same reason the
1403
- # no-progress guard refuses one -- degrading a summary is not a
1404
- # tighter compaction of it.
1405
- return {
1406
- "status": "all-pinned",
1407
- "kind": "compaction_blocked",
1408
- "text": ("Context is full, but everything foldable is pinned. "
1409
- "Unpin something with /unpin, or let more unpinned "
1410
- "turns accumulate."),
1411
- }
1412
-
1413
- original = len(segment_text)
1414
- target = _target_chars(original, settings["strength"])
1415
-
1416
- # M2's automatic fallback, built at last after three documents
1417
- # promised it for two sections. Forced only when there IS a previous
1418
- # summary to chain onto; VERBOSE because a configured strategy
1419
- # quietly doing the other thing is exactly what "(traced)" in the
1420
- # spec was about.
1421
- budget = _input_budget(model, provider_name)
1422
- forced_chain_note = ""
1423
- if (not chaining and previous is not None
1424
- and len(segment_text) // CHARS_PER_TOKEN > budget):
1425
- logger.warning(
1426
- "Compaction on thread %s: the rederive span is ~%s tokens "
1427
- "against a %s-token one-call budget; forcing chain onto the "
1428
- "previous summary.",
1429
- memory.thread_id, len(segment_text) // CHARS_PER_TOKEN, budget)
1430
- chaining = True
1431
- segment, segment_text = _build(True)
1432
- original = len(segment_text)
1433
- target = _target_chars(original, settings["strength"])
1434
- forced_chain_note = (" Chained onto the previous summary because "
1435
- "the span outgrew one call.")
1436
-
1437
- # Still over -- or no previous summary existed to chain onto. Truncate
1438
- # the OLDEST material (recent turns are the referent-heavy ones) and
1439
- # state the cut in both places the summary travels.
1440
- segment_text, truncation_notice = _truncate_oldest(segment_text, budget)
1441
- if truncation_notice:
1442
- # Both, as the forced-chain branch above does (#216, batch 213).
1443
- # The target used to stay the untruncated length's, so the
1444
- # instruction named one length and capped against another, and
1445
- # the strength the user set came out looser by their ratio.
1446
- original = len(segment_text)
1447
- target = _target_chars(original, settings["strength"])
1448
-
1449
- _set_compacting(True)
1450
- try:
1451
- # Batch 59. ONE span over the whole call, retries included: this is
1452
- # one compactor run that may take several calls to hit its target,
1453
- # and a shell drawing a row per attempt would report the retry loop
1454
- # as a stack of compactors. Inside the re-entrancy guard rather
1455
- # than around it, so the two brackets nest instead of interleaving.
1456
- with agent_activity.span(activity, agent.name, depth):
1457
- summary = _summarize(
1458
- RunAgentLoop, manager, agent, DEFAULT_SYSTEM_PROMPT,
1459
- segment_text, target, original, model, provider_name,
1460
- settings["max_retries"], authorization,
1461
- # §47. The compactor already had a span; what it did not
1462
- # have was a way to say WHOSE conversation it is
1463
- # summarising. It is a child of that thread in the only
1464
- # sense that matters -- the summary is of it -- so the
1465
- # link is not a convention, it is what happened.
1466
- parent_thread_id=memory.thread_id)
1467
- finally:
1468
- _set_compacting(False)
1469
-
1470
- if summary is None:
1471
- # #136, batch 20: this used to be kind=None -- invisible to both
1472
- # shells -- while its own WARNING fired inside _summarize on every
1473
- # evaluation. A compactor that returned nothing IS a failed
1474
- # compaction (AGENTS.md's containment rule says so), so it now
1475
- # rides compaction_failed: visible once per run through the loop's
1476
- # dedup, and the latch in _maybe_compact stops the per-step model
1477
- # calls the silence was hiding.
1478
- return {"status": "failed", "kind": "compaction_failed",
1479
- "text": "The compactor returned nothing usable."}
1480
-
1481
- if truncation_notice is not None:
1482
- # Deterministic rather than trusted from the model's compliance:
1483
- # the marker rides on the STORED summary, so the derived view --
1484
- # and everyone reading it later -- sees the cut even if the model
1485
- # never mentioned it.
1486
- summary = f"{summary}\n\n{truncation_notice}"
1487
-
1488
- strategy = "chain" if chaining else "rederive"
1489
- save_checkpoint(memory.thread_id, summary, watermark, strategy)
1490
- memory.apply_checkpoint()
1491
- folded = len(segment)
1492
- logger.info("Compacted thread %s: %s messages -> %s chars (%s).",
1493
- memory.thread_id, folded, len(summary), strategy)
1494
- return {
1495
- "status": "folded",
1496
- "kind": "compaction",
1497
- "text": f"{folded} earlier messages compacted into a summary"
1498
- + forced_chain_note,
1499
- }
1500
-
1501
-
1502
- def summarize_thread(thread_id, model: str, provider_name: str,
1503
- overrides: Optional[dict] = None,
1504
- authorization=None,
1505
- activity=None, depth: int = 1) -> Optional[dict]:
1506
- """Distil a WHOLE thread into a stored summary (ROADMAP_v2 §21c).
1507
-
1508
- Returns a notice dict carrying the summary, or None if the thread has
1509
- nothing in it. The shape matches compact()'s notices, so both shells
1510
- render it with code they already have.
1511
-
1512
- THIS IS NOT A COMPACTION and must never become one. compact() folds a
1513
- span of the thread it is given, changing what the model sees on the next
1514
- turn; this reads a thread and writes a description of it, leaving the
1515
- thread untouched -- which is what lets `/ref` inject one thread's summary
1516
- into a different thread, and what lets `/summary` show one without
1517
- quietly shortening the conversation the user is having (M20).
1518
-
1519
- THE ARCHIVE, NEVER THE DERIVED VIEW. `archive_history` returns every
1520
- message ever written, so a summary of a compacted thread describes the
1521
- conversation rather than describing the summary of it. A view-based
1522
- version would degrade a little on every compaction, exactly the chaining
1523
- loss M2 arranges the fold to avoid.
1524
-
1525
- CACHED, AND STALENESS IS DETECTED RATHER THAN ASSUMED. The stored row
1526
- carries the last archive position it accounts for, so `advances()` --
1527
- which already answers "has this thread moved past that point?" for
1528
- compaction -- says whether the summary still holds. An unchanged thread
1529
- therefore costs no model call however many times it is referenced, and a
1530
- grown one is re-summarized rather than silently served stale.
1531
-
1532
- A THREAD ALREADY SHORTER THAN THE TARGET IS NOT SENT TO A MODEL. Its
1533
- rendered text IS its own best summary, and asking a model to compress
1534
- three messages into more characters than they occupy spends a call to
1535
- make the answer worse. Same instinct as compact()'s no-progress-no-call
1536
- guard.
1537
-
1538
- The target is an ABSOLUTE character budget (`config.SUMMARY_TARGET_CHARS`),
1539
- not `_target_chars`' strength ratio. A ratio is right for a fold, where
1540
- the summary replaces the span it came from and scales with it. It is wrong
1541
- here: §21c's consumer is a prompt tier present on EVERY turn of the
1542
- referencing thread, so a proportional target would let one big thread
1543
- inject tens of kilobytes into every call indefinitely.
1544
- """
1545
- from agents.manager import manager
1546
- from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop
1547
- from storage import (
1548
- advances,
1549
- archive_history,
1550
- last_message_id,
1551
- latest_thread_summary,
1552
- save_thread_summary,
1553
- )
1554
-
1555
- if _is_compacting():
1556
- return None
1557
-
1558
- watermark = last_message_id(thread_id)
1559
- if watermark is None:
1560
- return None
1561
-
1562
- existing = latest_thread_summary(thread_id)
1563
- if existing is not None and not advances(
1564
- thread_id, existing["covers_up_to_message_id"], watermark):
1565
- return {
1566
- "kind": "thread_summary",
1567
- "text": existing["summary_text"],
1568
- "thread_id": str(thread_id),
1569
- "fresh": False,
1570
- }
1571
-
1572
- thread_text = _as_text(archive_history(thread_id))
1573
- original = len(thread_text)
1574
- target = config.SUMMARY_TARGET_CHARS
1575
-
1576
- if original <= target:
1577
- save_thread_summary(thread_id, thread_text, watermark)
1578
- return {
1579
- "kind": "thread_summary",
1580
- "text": thread_text,
1581
- "thread_id": str(thread_id),
1582
- "fresh": True,
1583
- "verbatim": True,
1584
- }
1585
-
1586
- # #90's gate on the second consumer. A thread summary's input is
1587
- # bounded by NOTHING else -- compact()'s span at least waits for a
1588
- # threshold -- and T4 documents what tool rows weigh. Reserve room for
1589
- # the summary this call is meant to PRODUCE, then truncate the oldest
1590
- # material with the cut stated in the instruction AND in the stored
1591
- # row, so every referencing thread sees it.
1592
- budget = max(1_000, _input_budget(model, provider_name)
1593
- - config.SUMMARY_TARGET_CHARS // CHARS_PER_TOKEN)
1594
- thread_text, truncation_notice = _truncate_oldest(thread_text, budget)
1595
- if truncation_notice:
1596
- original = len(thread_text)
1597
-
1598
- agent = manager.get(config.COMPACTOR_AGENT)
1599
- if agent is None:
1600
- logger.warning(
1601
- "A thread summary was wanted but the %r agent is not available; "
1602
- "skipped.", config.COMPACTOR_AGENT)
1603
- return None
1604
-
1605
- settings = config_loader.effective_compaction(overrides)
1606
- # The guard for the same reason compact() sets it (M3): the compactor is
1607
- # an agent, so summarizing runs the loop, which evaluates the compaction
1608
- # trigger. Its own thread is one turn long and would not trip it today,
1609
- # which is exactly the kind of "cannot happen yet" that stops being true
1610
- # quietly.
1611
- _set_compacting(True)
1612
- try:
1613
- # Batch 59, and see compact() above for why one span covers the
1614
- # retries. §21c's /summary runs this from its own worker, so it is
1615
- # the one compactor run with no parent turn under it.
1616
- with agent_activity.span(activity, agent.name, depth):
1617
- summary = _summarize(
1618
- RunAgentLoop, manager, agent, DEFAULT_SYSTEM_PROMPT,
1619
- thread_text, target, original, model, provider_name,
1620
- settings["max_retries"], authorization)
1621
- finally:
1622
- _set_compacting(False)
1623
-
1624
- if summary is None:
1625
- return None
1626
-
1627
- if truncation_notice is not None:
1628
- # Same determinism rule as compact(): the marker rides on the
1629
- # stored row regardless of whether the model mentioned the cut.
1630
- summary = f"{summary}\n\n{truncation_notice}"
1631
-
1632
- save_thread_summary(thread_id, summary, watermark)
1633
- logger.info("Summarized thread %s: %s chars -> %s.",
1634
- thread_id, original, len(summary))
1635
- return {
1636
- "kind": "thread_summary",
1637
- "text": summary,
1638
- "thread_id": str(thread_id),
1639
- "fresh": True,
1640
- }
1641
-
1642
-
1643
- def _summarize(loop_cls, manager, agent, base_prompt, segment_text, target,
1644
- original, model, provider_name, max_retries, authorization,
1645
- parent_thread_id=None):
1646
- """Run the compactor, retrying while the summary overshoots its target.
1647
-
1648
- STRUCTURALLY §3's JSON-retry loop with a length constraint in place of
1649
- a parse -- a corrective follow-up into the SAME thread, so the model
1650
- sees its own output and can tighten it, bounded by a retry cap.
1651
- Deliberately not routed through core/reasoning/json_retry.py: that
1652
- module is pipeline-shaped (it takes a run trace and names passes), and
1653
- bending it to serve memory would invert the dependency for three lines
1654
- of shared structure.
1655
-
1656
- UNDERSHOOTING IS NOT AN ERROR. A summary tighter than asked for has
1657
- already done the job, and rejecting it would spend a second model call
1658
- to make the context bigger.
1659
-
1660
- A summary still too long after the last retry is USED ANYWAY, with a
1661
- warning. It is smaller than what it replaces, which is the whole point;
1662
- discarding it would spend the calls and keep the full history, leaving
1663
- the thread exactly as stuck as before with less budget to fix it.
1664
- """
1665
- from core.loop import advertisement_facts
1666
-
1667
- context = manager.active_context(agent)
1668
- # #228: the catalogs this prompt carries are decided by the run it is
1669
- # for, through the bundle that run is given below -- the reviewer's
1670
- # rule (core/reasoning/review.py). With system_prompt_for's attended
1671
- # defaults this was right only while compactor.md's empty
1672
- # allowed_tools kept both catalog tools out; a widening would have
1673
- # reopened #68 on every automatic compaction of a headless run.
1674
- callable_only, granted = advertisement_facts(authorization)
1675
- system_prompt = manager.system_prompt_for(
1676
- agent, base_prompt, context=context,
1677
- callable_only=callable_only, granted=granted)
1678
- tolerance = int(target * (1 + config.COMPACTION_RATIO_TOLERANCE))
1679
-
1680
- response = loop_cls.run_agent_conversation(
1681
- user_goal=_instruction(segment_text, target, original),
1682
- model=agent.model or model,
1683
- provider_name=agent.provider or provider_name,
1684
- max_steps=1,
1685
- context=context,
1686
- system_prompt=system_prompt,
1687
- authorization=authorization,
1688
- # §27, and NOT in that section's spec: the compactor is a fifth
1689
- # thread source nobody had counted. Every automatic compaction of a
1690
- # long chat creates one of these, so on exactly the threads §21a
1691
- # exists to serve, the picker filled up with the machinery that
1692
- # served them. The compactor is an agent, so it is labelled like the
1693
- # other agent-shaped runs.
1694
- thread_kind=THREAD_KIND_SUBAGENT,
1695
- # §47. No parent CALL -- no tool started this -- so the run is
1696
- # findable by the conversation it belongs to and by nothing
1697
- # else, which is the honest shape for a thread the harness
1698
- # opened on its own initiative.
1699
- thread_parent=parent_thread_id,
1700
- thread_agent=agent.name,
1701
- )
1702
- summary = (response.text or "").strip()
1703
-
1704
- for _ in range(max_retries):
1705
- if not summary:
1706
- logger.warning("Compactor returned nothing; compaction skipped.")
1707
- return None
1708
- if len(summary) <= tolerance:
1709
- return summary
1710
- response = loop_cls.continue_conversation(
1711
- thread_id=response.thread_id,
1712
- message=(
1713
- f"That summary is {len(summary)} characters; the target is "
1714
- f"{target}. Tighten it -- drop the least important material "
1715
- f"rather than making the remaining facts vaguer. Output only "
1716
- f"the summary."),
1717
- system_prompt=system_prompt,
1718
- model=agent.model or model,
1719
- provider_name=agent.provider or provider_name,
1720
- max_steps=1,
1721
- context=context,
1722
- authorization=authorization,
1723
- )
1724
- summary = (response.text or "").strip()
1725
-
1726
- if not summary:
1727
- logger.warning("Compactor returned nothing; compaction skipped.")
1728
- return None
1729
- if len(summary) > tolerance:
1730
- logger.warning(
1731
- "Compactor missed its target after %s retries (%s chars against a "
1732
- "target of %s); using it anyway -- it is still smaller than the "
1733
- "%s characters it replaces.", max_retries, len(summary), target,
1734
- original)
1735
- return summary
1
+ """
2
+ core/compaction.py
3
+
4
+ ROADMAP_v2 §21. Decides WHEN a thread should be compacted, WHAT may be
5
+ folded, and runs the compactor agent to do it.
6
+
7
+ The archive is never touched. Compaction adds a CompactionCheckpoint row
8
+ and nothing else; storage.archive_history() keeps returning every message
9
+ ever written, however many times this has run (§21 AC1). That is the property
10
+ that makes an early, frequent trigger safe -- nothing is destroyed, only
11
+ hidden from the next call.
12
+
13
+ WHAT THIS MODULE OWNS
14
+ should_compact() the trigger, in both its modes
15
+ compactable_span() what may be folded, and the three floors that bound it
16
+ compact() run the compactor, record the checkpoint, rebuild the view
17
+
18
+ WHAT IT DOES NOT OWN
19
+ Where the trigger is evaluated -- core/loop.py calls in, at a turn
20
+ boundary and between steps. Assembling the derived view -- core/memory.py
21
+ owns that, and compact() asks it to rebuild rather than splicing a
22
+ summary in from here. Resolving settings -- core/config_loader.py's
23
+ effective_compaction(), because it owns the merge and this module reaches
24
+ agents.manager, which imports it.
25
+
26
+ MEASUREMENT IS BY CHARACTERS, AND SAYS SO (M10). §21 asks for the summary's
27
+ tokens to be counted; no tokenizer is available offline, and
28
+ usage["input_tokens"] measures a whole prompt rather than a segment of one.
29
+ Chars/4 applied to both sides of a ratio is self-consistent, which is all a
30
+ ratio check needs -- it is never compared against a provider's count.
31
+ """
32
+
33
+ import json
34
+ import logging
35
+ import re
36
+ import threading
37
+ from typing import Optional
38
+
39
+ import config
40
+ from core import agent_activity, config_loader, model_windows, session
41
+ from storage import THREAD_KIND_SUBAGENT
42
+
43
+ logger = logging.getLogger(__name__)
44
+
45
+ # M10. Rough and deliberately uncalibrated: it appears on both sides of
46
+ # every comparison this module makes, so its accuracy cancels out. Never
47
+ # compare a value derived from it against a provider's token count.
48
+ CHARS_PER_TOKEN = 4
49
+
50
+ # ROADMAP_v3 §81 (IM8). What one image weighs in that proxy, in tokens.
51
+ #
52
+ # A FIXED number, because the alternative is decoding every image to learn
53
+ # its dimensions, which would take an imaging dependency this harness does
54
+ # not carry. 1,600 is the top of Anthropic's own estimate (width x height /
55
+ # 750, on an image it has already scaled to about 1.15 megapixels), so a
56
+ # large image is counted at roughly its real cost and a small one is
57
+ # overcounted. Overcounting folds a little early; undercounting would let a
58
+ # thread of screenshots run past the window. Counting an image by its base64
59
+ # LENGTH would be the third option, and the worst: a 1 MB file is about 1.3
60
+ # million characters, which reads as 330,000 tokens and folds at once.
61
+ IMAGE_TOKEN_ESTIMATE = 1600
62
+ _IMAGE_CHARS = IMAGE_TOKEN_ESTIMATE * CHARS_PER_TOKEN
63
+
64
+
65
+ def _image_count(images) -> int:
66
+ """How many images one row or message carries (IM8): the decoded list on
67
+ a neutral message, the JSON text `MessageLog.images` stores on an archive
68
+ row, or nothing."""
69
+ if not images:
70
+ return 0
71
+ if isinstance(images, str):
72
+ try:
73
+ images = json.loads(images)
74
+ except ValueError:
75
+ return 0
76
+ return len(images) if isinstance(images, list) else 0
77
+
78
+
79
+ def _row_chars(row) -> int:
80
+ """One archive row's size in the proxy: its persisted content, plus IM8's
81
+ fixed weight per image. EVERY row-size sum below goes through here, so a
82
+ floor and the pin cap cannot disagree about what an image costs."""
83
+ return len(row["content"]) + _image_count(row.get("images")) * _IMAGE_CHARS
84
+
85
+ # The re-entrancy guard (M3). The compactor is an agent, so compacting runs
86
+ # the loop, which evaluates the trigger, which could compact.
87
+ #
88
+ # PER THREAD SINCE BATCH 75, AND IT WAS A MODULE FLAG UNTIL THEN. That flag
89
+ # said: "a thread-local would be more precise, but the loop is synchronous
90
+ # and a compaction runs to completion before its caller resumes -- and a
91
+ # module flag has the property that matters more: it is impossible to be
92
+ # half-set." True when written, and §47's NA9 removed the premise. Two
93
+ # children of one response each reach `_maybe_compact` on their own thread,
94
+ # and a shared flag then does two wrong things:
95
+ #
96
+ # * the second child's `should_compact` returns "" and its compaction is
97
+ # silently skipped for that step, because a sibling is mid-fold;
98
+ # * whichever finishes first clears the flag while the other's compactor
99
+ # is still running, reopening exactly the window this guard closes.
100
+ #
101
+ # Neither is loud: a skipped compaction self-corrects on the next step, so
102
+ # the visible symptom would be a thread running into a provider's context
103
+ # limit with a guard that looked like it was working. It was the seventh
104
+ # member of slice 8's "six things that were only safe alone", found by
105
+ # reading this comment against what NA9 had done to it.
106
+ #
107
+ # The half-set property survives, which is why this is still a flag and not
108
+ # a lock: one bool per thread, set and cleared in a `finally` by the frame
109
+ # that owns it. Nothing here serialises anything -- two conversations
110
+ # folding at once is correct, since each needs its own fold.
111
+ #
112
+ # A FUNCTION RATHER THAN A BARE ATTRIBUTE, and the module name is GONE
113
+ # rather than kept as an alias: `if _compacting:` against a callable is
114
+ # always true, so a reader left holding the old name has to fail at import
115
+ # instead of quietly disabling every compaction in the process.
116
+ _reentrancy = threading.local()
117
+
118
+
119
+ def _is_compacting() -> bool:
120
+ """Whether THIS thread is already inside a compaction."""
121
+ return getattr(_reentrancy, "active", False)
122
+
123
+
124
+ def _set_compacting(active: bool) -> None:
125
+ """Mark this thread as compacting, or done."""
126
+ _reentrancy.active = bool(active)
127
+
128
+
129
+ def _chars(messages) -> int:
130
+ """Size of a neutral-shape message list, in characters."""
131
+ total = 0
132
+ for message in messages:
133
+ total += len(str(message.get("content", "")))
134
+ total += len(str(message.get("text", "")))
135
+ total += _image_count(message.get("images")) * _IMAGE_CHARS
136
+ for call in message.get("tool_calls", ()) or ():
137
+ total += len(str(call))
138
+ return total
139
+
140
+
141
+ def estimated_tokens(messages) -> int:
142
+ """A character-based estimate of what a message list will cost to send.
143
+
144
+ Only used when nothing has been MEASURED yet -- a thread written before
145
+ §21 existed, resumed for the first time. Every other evaluation reads
146
+ memory.last_input_tokens, which is the provider's own count of exactly
147
+ what it was sent and needs no estimate at all.
148
+ """
149
+ return _chars(messages) // CHARS_PER_TOKEN
150
+
151
+
152
+ # Models already warned about, so the fallback notice is said once per
153
+ # model rather than once per evaluation. Deduplicated on the MODEL, not
154
+ # with a single boolean, for the same reason core/loop.py's
155
+ # _headless_notices_shown keys on the hidden SET: a run that switches
156
+ # model (or a pipeline whose critic model differs, §11) must still hear
157
+ # about the second one.
158
+ _context_window_warned: set = set()
159
+
160
+ # The same once-per-model discipline for a DIFFERENT warning: a window so
161
+ # small that the dependent floor leaves the trigger no usable headroom
162
+ # (ROADMAP_v3 §65 A24). A separate set rather than a shared one, keyed on
163
+ # the PAIR, because the two warnings answer different questions: the one
164
+ # above is about a model missing from a table, which has no provider
165
+ # dimension, while this one is about the number a provider REPORTED -- and
166
+ # the same model name behind a gateway and behind its own vendor can report
167
+ # different windows, so the pair is the thing that was warned about. Sharing
168
+ # one set would also mean whichever fired first silenced the other.
169
+ _floor_warned: set = set()
170
+
171
+ # And a third, for the case A24 left out on purpose: the headroom CAP, not
172
+ # the floor, leaves less room than one bounded read (TECHNICAL_DEBT 96,
173
+ # batch 220). Its own set, keyed the same way and for the same reasons.
174
+ _read_warned: set = set()
175
+
176
+ # Threads whose turn count has already been reported as yielding (#217,
177
+ # batch 221), so the INFO line is said once per thread. Keyed on the
178
+ # THREAD, not the model: the condition is a property of the conversation.
179
+ _yield_logged: set = set()
180
+
181
+
182
+ # A trailing release date, as Anthropic and Google spell it.
183
+ _DATE_SUFFIX = re.compile(r"-\d{8}$")
184
+
185
+ # Region prefixes an inference gateway prepends, as an ALLOWLIST rather
186
+ # than a dot-split. Two entries in the table -- `gpt-5.1` and
187
+ # `qwen3.8-max-preview` -- contain dots inside the model name itself, so a
188
+ # general "strip up to the first dot" rule would corrupt exactly the names
189
+ # it was meant to preserve. Matching a known set cannot.
190
+ _REGION_PREFIXES = ("us.", "eu.", "apac.", "us-gov.")
191
+
192
+
193
+ def _normalized(model: str) -> str:
194
+ """A model id reduced to the form MODEL_CONTEXT_WINDOWS is keyed in.
195
+
196
+ LOOKUP ONLY. This never touches what is sent on the wire -- the model
197
+ string the provider receives is always the one the caller supplied.
198
+
199
+ Exact matching alone is why `claude-sonnet-5-20260724` used to resolve
200
+ to the 200k default while `claude-sonnet-5` sat in the table at a
201
+ million: a 5x undershoot that is silent after the first warning, and
202
+ which reaches summarize_thread()'s truncation gate, not just the
203
+ backstop. The table itself demonstrated the problem -- it keyed one
204
+ Claude entry with a date suffix and five without.
205
+
206
+ Deliberately narrow, and the rules only ever REMOVE a decoration that
207
+ a gateway added:
208
+
209
+ anthropic/claude-opus-5 -> claude-opus-5 (OpenRouter style)
210
+ us.anthropic.claude-opus-5 -> claude-opus-5 (Bedrock style)
211
+ claude-sonnet-5-20260724 -> claude-sonnet-5
212
+ gpt-5.1 -> gpt-5.1 (untouched)
213
+ qwen3.8-max-preview -> qwen3.8-max-preview
214
+
215
+ An id that fits no rule is returned unchanged, so an unrecognised name
216
+ still MISSES and still warns. That direction is deliberate: a loud
217
+ miss costs an early compaction, a wrong prefix match costs a silently
218
+ wrong window, and this table feeds a lossy truncation.
219
+ """
220
+ name = model.strip()
221
+ if "/" in name:
222
+ name = name.rsplit("/", 1)[-1]
223
+ for prefix in _REGION_PREFIXES:
224
+ if name.startswith(prefix):
225
+ name = name[len(prefix):]
226
+ break
227
+ # Bedrock spells the vendor as a dotted segment after the region.
228
+ if name.startswith("anthropic."):
229
+ name = name[len("anthropic."):]
230
+ return _DATE_SUFFIX.sub("", name)
231
+
232
+
233
+ def context_limit(model: str, provider_name: Optional[str] = None) -> int:
234
+ """The model's context window, for the pipeline backstop (M6).
235
+
236
+ FOUR SOURCES, most local first:
237
+
238
+ 0. A REMEMBERED override for this exact (provider, model) --
239
+ core/model_windows.py, written by /window and kept across
240
+ launches (batch 44). It wins because it is the one source a
241
+ human set on purpose, and because the query it overrides can be
242
+ confidently wrong: a gateway may report its own default rather
243
+ than the deployment's, and a self-hosted endpoint's window is
244
+ a fact only its operator has. Everywhere else in this project a
245
+ measured value beats a configured one; here the direction is
246
+ deliberately inverted.
247
+ 1. What the provider SAID, via core.client.known_context_window --
248
+ a cache-only read, primed by core/loop.py before every send. §21
249
+ rejected querying on the belief that no provider in the roster
250
+ could answer; re-measured, Anthropic reports max_input_tokens on
251
+ the very ModelInfo the effort query already fetches, Google
252
+ reports input_token_limit, and Groq/Mistral/Together/OpenRouter
253
+ report a window under one of four field names. A queried answer
254
+ also beats the table on a point the table cannot reach: it is
255
+ what THIS account actually has, not what the model can have.
256
+ 2. config.MODEL_CONTEXT_WINDOWS, normalized (see _normalized), which
257
+ still answers for OpenAI, DeepSeek and Perplexity -- they report
258
+ nothing, which is why §21's conclusion outlived its premise.
259
+ 3. DEFAULT_CONTEXT_WINDOW, warned.
260
+
261
+ Warned on fallback, per §21: a wrong-by-default window means the
262
+ backstop fires at the wrong time in whichever direction the guess is
263
+ wrong, and silent guessing turns a tuning problem into a mystery. Much
264
+ less load-bearing than §21 assumed, though -- M1 moved the ordinary
265
+ trigger off this table entirely, so a missing entry costs a mistimed
266
+ backstop and a mistimed summarizer input budget rather than mistimed
267
+ compaction.
268
+
269
+ ONCE PER MODEL. This is called from thresholds(), which
270
+ should_compact() calls on EVERY evaluation -- and _maybe_compact runs
271
+ at the top of every step of every turn, so in a research run that is
272
+ twice a step across ten passes. Unbounded repetition of a line the
273
+ user can do nothing more about after reading it once is how a warning
274
+ that matters gets trained past, and on the TUI it was also painting
275
+ over the screen.
276
+
277
+ `provider_name` is optional so that every existing caller keeps
278
+ working; without it only sources 2 and 3 are available, which is
279
+ exactly the behaviour that predated the query.
280
+
281
+ THIS IS NOW ON EVERY THREAD'S PATH, not just a research pass's. Batch
282
+ 44 made the working-set trigger a fraction of what this returns, so a
283
+ wrong answer here no longer costs a mistimed backstop -- it decides
284
+ when every chat compacts. That is why source 0 exists at the user tier
285
+ and why the fallback below still warns.
286
+ """
287
+ override = model_windows.window_for(provider_name, model)
288
+ if override:
289
+ return override
290
+
291
+ if provider_name:
292
+ # Imported HERE, not at module scope. core/client.py defers its SDK
293
+ # imports to keep `--help` fast (see its header), and this module is
294
+ # reached from agents.manager, so a top-level import would both undo
295
+ # that and add an import cycle. Guarded because a failure to read a
296
+ # cache must never be the reason a thread cannot compact.
297
+ try:
298
+ from core import client as _client
299
+
300
+ queried = _client.known_context_window(provider_name, model)
301
+ except Exception: # pragma: no cover - defensive
302
+ queried = None
303
+ if queried:
304
+ return queried
305
+
306
+ window = config.MODEL_CONTEXT_WINDOWS.get(_normalized(model))
307
+ if window is None:
308
+ if model not in _context_window_warned:
309
+ _context_window_warned.add(model)
310
+ logger.warning(
311
+ "No context window known for model %r%s; assuming %s. Set it "
312
+ "with /window (remembered for this model) or add it to "
313
+ "config.MODEL_CONTEXT_WINDOWS -- the compaction trigger, the "
314
+ "research backstop and the summarizer's input budget all "
315
+ "fire against this number.", model,
316
+ f" on {provider_name}" if provider_name else "",
317
+ config.DEFAULT_CONTEXT_WINDOW)
318
+ return config.DEFAULT_CONTEXT_WINDOW
319
+ return window
320
+
321
+
322
+ def headroom_for(window: int) -> int:
323
+ """Tokens held between the trigger and `window` -- a CLAMPED share.
324
+
325
+ THE HEADROOM IS THE POINT, and batch 119 is where that got said out
326
+ loud. The trigger's job is not to cap the thread at a tidy percentage;
327
+ it is to leave room for the step that runs AFTER it fires, because
328
+ nothing in this harness recovers from a prompt that overflows the
329
+ window. There is no context_length_exceeded handler anywhere in
330
+ core/ -- grep for one. The provider raises, core/loop.py retries the
331
+ identical oversized prompt three times, and the turn dies. This number
332
+ is the only thing standing between a thread and that.
333
+
334
+ SO A BARE SHARE IS WRONG AT BOTH ENDS, which is the same shape of
335
+ error batch 44 corrected in the other direction. Batch 44 replaced a
336
+ flat 40k margin with a share because 40k is a rounding error under 1M
337
+ and strangling under 64k; a bare share has the mirror-image defect,
338
+ because what it holds CONSTANT is the percentage while the thing the
339
+ headroom must contain -- one step's growth -- does not scale with the
340
+ window at all. A single `max_read_chars` result is 12,500 proxy tokens
341
+ whether the model holds 64k or a million. 0.10 of 1M is 100k, which is
342
+ more than any step needs; 0.10 of 64k is 6,553, which one ordinary file
343
+ read overflows.
344
+
345
+ Hence a floor AND a cap, and each has a different job:
346
+
347
+ * COMPACTION_MIN_HEADROOM_TOKENS keeps a small window usable. It
348
+ binds under roughly 160k and nowhere above it, so a 262k or 1M
349
+ thread gets the fraction exactly as configured.
350
+ * COMPACTION_MAX_HEADROOM_FRACTION keeps the floor from eating a
351
+ small window whole -- 16k of a 32k window is half of it -- and it
352
+ is what keeps the resulting trigger positive at the bottom of the
353
+ range.
354
+
355
+ AND THAT IS NOT SUFFICIENT, which is TECHNICAL_DEBT 42 and the reason
356
+ derived_trigger() now floors below. This bullet used to end "and above
357
+ keep_recent_tokens at the bottom of the range, where
358
+ effective_compaction() would otherwise raise" -- true, and it names
359
+ ONE of the two dependent floors that function validates. The cap holds
360
+ the trigger at 0.75*window down here, so it clears keep_recent_tokens
361
+ (4,000) from a window of 5,334 up and clears warning_margin_tokens
362
+ (8,000) only from 10,667 up. Measured: keep_recent_tokens never bites
363
+ first anywhere in the range, which is exactly what made checking only
364
+ it read as covered.
365
+
366
+ MEASURED, not reasoned: the thread that produced this batch grew by
367
+ 31,733 proxy tokens in ONE step (a single 117k-character arxiv_search
368
+ result). At 0.85 its 262k window left 39,322 and that step fit; a bare
369
+ 0.90 leaves 26,215 and it does not.
370
+ """
371
+ # `window - int(fraction * window)` rather than
372
+ # `(1 - fraction) * window`, so the unclamped case reproduces the
373
+ # fraction EXACTLY. The two differ by the truncation: 0.10 * 262144 is
374
+ # 26214.4, and truncating the headroom down put the trigger one token
375
+ # ABOVE int(0.90 * 262144). One token is harmless and an arithmetic
376
+ # identity that holds only approximately is not -- every documented
377
+ # table would be off by one with nothing to point at.
378
+ share = window - int(config.COMPACTION_TRIGGER_FRACTION * window)
379
+ floor = config.COMPACTION_MIN_HEADROOM_TOKENS
380
+ cap = config.COMPACTION_MAX_HEADROOM_FRACTION * window
381
+ return int(min(max(share, floor), cap))
382
+
383
+
384
+ def _dependent_floor() -> int:
385
+ """The smallest trigger effective_compaction() will accept.
386
+
387
+ TECHNICAL_DEBT 42. That function validates the trigger against two
388
+ settings of identical form -- `warning_margin_tokens` and
389
+ `keep_recent_tokens`, each of which must be STRICTLY below it -- so the
390
+ smallest acceptable trigger is one above the larger of the two.
391
+
392
+ READ, NEVER HARDCODED, and that is the whole point of the helper. The
393
+ numbers are 8,000 and 4,000 today; a literal 8,001 here would be
394
+ correct until someone edited config.yaml:830, and then it would be a
395
+ floor that no longer matches the validator it exists to satisfy. This
396
+ reads the SAME resolution the validator reads, so the two cannot drift
397
+ apart -- which is item 41's lesson applied to the fix and not only to
398
+ the register entry.
399
+
400
+ Bare, with no overrides, deliberately: a per-invocation
401
+ `trigger_tokens` is the value being floored and must not decide its own
402
+ floor, while the two margins resolve identically either way.
403
+
404
+ COSTS ONE MERGE on should_compact()'s path. Measured: 3.267us against
405
+ thresholds()'s 4.918us, so 66% of it in relative terms and 0.065ms per
406
+ step of a research run in absolute ones -- against 4.696ms for one
407
+ ordinary tool result's redaction pass. The relative figure is the one
408
+ that looks alarming and the absolute figure is the one that is true.
409
+
410
+ DEFENSIVE ABOUT ITS OWN READ. effective_compaction() cannot raise under
411
+ config.yaml's 40,000 default, but a user settings.json naming a small
412
+ `trigger_tokens` makes it raise on the way to telling us the margins --
413
+ and derived_trigger() has callers outside thresholds(). A floor that
414
+ cannot be computed must never become the reason a thread cannot
415
+ compact, so this falls back to the config.py constants, which are the
416
+ same numbers one tier down.
417
+ """
418
+ try:
419
+ settings = config_loader.effective_compaction()
420
+ margin = settings["warning_margin_tokens"]
421
+ keep_recent = settings["keep_recent_tokens"]
422
+ except Exception: # noqa: BLE001 -- see above
423
+ margin = config.COMPACTION_WARNING_MARGIN_TOKENS
424
+ keep_recent = config.COMPACTION_KEEP_RECENT_TOKENS
425
+ return max(margin, keep_recent) + 1
426
+
427
+
428
+ def _warn_if_the_floor_left_no_room(model: str, provider_name: Optional[str],
429
+ window: int, share: int, floor: int,
430
+ trigger: int) -> None:
431
+ """Say ONCE, per (provider, model), that the floor is now the ceiling.
432
+
433
+ TECHNICAL_DEBT 42 raised a floor under the derived trigger so that a
434
+ small window could not make effective_compaction() raise on every
435
+ turn. The floor is read from the same settings the validator reads, and
436
+ it is applied WITH NO REFERENCE TO THE WINDOW -- so under the shipped
437
+ 8,000/4,000 margins it is 8,001 whatever the model holds, and at or
438
+ below 8,000 the trigger it produces is ABOVE the window. `used` is the
439
+ provider's own count of what it was sent, so it can never reach a
440
+ trigger above the window: compaction never fires, silently, and the
441
+ only line the user sees is the warn branch's "approaching the
442
+ compaction threshold", which collapses to warn_at == 1 down here and is
443
+ therefore both constant and false.
444
+
445
+ That is precisely the outcome item 42's own fix section rejected --
446
+ "compaction would then silently never run on that model, which is the
447
+ quiet-failure class this project keeps closing" -- arrived at from the
448
+ other side. The floor stays, because the raise it removed was worse;
449
+ what was missing is this line.
450
+
451
+ FIRES ONLY WHERE THE FLOOR IS THE OPERATIVE VALUE, which is A24's
452
+ ruling and is measured rather than guessed: the floor binds at or below
453
+ a 10,666-token window and nowhere above it, because headroom's cap
454
+ holds the share-derived trigger at 0.75*window down there. A window of
455
+ 16,384 or 32,768 also leaves less headroom than one bounded read
456
+ (12,500 proxy tokens), but the CAP is what bound it, the cap is
457
+ deliberate (see headroom_for), and the only remedy there is a bigger
458
+ model -- so a warning naming two settings would name the wrong thing.
459
+ That case is TECHNICAL_DEBT 96, and since batch 220 it has a line of its
460
+ own, `_warn_if_one_read_cannot_fit`, naming the read instead.
461
+
462
+ Two wordings for one condition, because the remedy differs: at or above
463
+ the window the trigger cannot be reached at all, and just below it the
464
+ thread folds but the next step has almost nothing to grow into.
465
+ """
466
+ if floor < share:
467
+ return
468
+ one_read = int(config.MAX_READ_CHARS) // CHARS_PER_TOKEN
469
+ if window - trigger >= one_read:
470
+ return
471
+ key = (provider_name or "", model)
472
+ if key in _floor_warned:
473
+ return
474
+ _floor_warned.add(key)
475
+ where = f" on {provider_name}" if provider_name else ""
476
+ settings = (f"compaction.warning_margin_tokens "
477
+ f"({config.COMPACTION_WARNING_MARGIN_TOKENS}) and "
478
+ f"compaction.keep_recent_tokens "
479
+ f"({config.COMPACTION_KEEP_RECENT_TOKENS})")
480
+ if trigger >= window:
481
+ logger.warning(
482
+ "Compaction can NEVER fire for %r%s: its context window is %s "
483
+ "tokens and the smallest trigger the settings allow is %s, which "
484
+ "is above it. The thread will grow until the provider refuses "
485
+ "the request. The floor is one token above the larger of %s -- "
486
+ "lowering them lowers it.", model, where, window, trigger,
487
+ settings)
488
+ return
489
+ logger.warning(
490
+ "Compaction for %r%s can only fire with %s tokens of headroom left "
491
+ "(window %s, trigger %s, held up by the floor rather than derived "
492
+ "from the window): one bounded tool read is about %s proxy tokens, "
493
+ "so the step after a fold can still overflow. The floor is one token "
494
+ "above the larger of %s -- lowering them lowers it.",
495
+ model, where, window - trigger, window, trigger, one_read, settings)
496
+
497
+
498
+ def _warn_if_one_read_cannot_fit(model: str, provider_name: Optional[str],
499
+ window: int, share: int, floor: int,
500
+ trigger: int) -> None:
501
+ """Say ONCE, per (provider, model), that one read can overflow the window.
502
+
503
+ TECHNICAL_DEBT 96 (#246, batch 220): the case the warning above leaves
504
+ out on purpose. On a 16,384- or 32,768-token window the floor does not
505
+ bind; headroom_for's CAP does, and it leaves 4,096 or 8,192 tokens
506
+ between the trigger and the window -- less than one bounded read's
507
+ 12,500. A thread just under the trigger takes one large `read`, the
508
+ prompt overflows, and nothing in core/ recovers from that.
509
+
510
+ A24 was right that naming the two margins would name the wrong remedy.
511
+ The right one is the READ: `max_read_chars` is a setting, and a value
512
+ that fits the headroom keeps one read inside the window. The owner chose
513
+ to say so over shrinking reads per model, which would need the window
514
+ plumbed into every tool that reads the global. It applies to every
515
+ model, and the line says that too.
516
+ """
517
+ if floor >= share:
518
+ return # the floor binds; the warning above owns that case
519
+ one_read = int(config.MAX_READ_CHARS) // CHARS_PER_TOKEN
520
+ headroom = window - trigger
521
+ if headroom >= one_read:
522
+ return
523
+ key = (provider_name or "", model)
524
+ if key in _read_warned:
525
+ return
526
+ _read_warned.add(key)
527
+ where = f" on {provider_name}" if provider_name else ""
528
+ logger.warning(
529
+ "Compaction for %r%s fires at %s tokens of a %s-token window, leaving "
530
+ "%s tokens of headroom: less than one bounded tool read "
531
+ "(max_read_chars is %s characters, about %s tokens), so one large "
532
+ "read just below the trigger can overflow the window and end the "
533
+ "turn. A max_read_chars of %s or less in config.yaml keeps a read "
534
+ "inside it; it applies to every model.",
535
+ model, where, trigger, window, headroom, config.MAX_READ_CHARS,
536
+ one_read, headroom * CHARS_PER_TOKEN)
537
+
538
+
539
+ def derived_trigger(model: str, provider_name: Optional[str] = None) -> int:
540
+ """The working-set trigger for this model: its window less headroom.
541
+
542
+ Batch 44's reversal of M1, as corrected by batch 119. The argument for
543
+ deriving this from the window at all is on COMPACTION_TRIGGER_FRACTION;
544
+ the argument for the clamps is on headroom_for() above.
545
+
546
+ STILL NOT `window - margin`, which is the BACKSTOP's shape and is what
547
+ batch 44 rejected: that is a FIXED margin, right at neither end of the
548
+ roster. This is a share that may not shrink below an absolute nor grow
549
+ past a share -- which is the same number at every window above ~160k
550
+ and a floor below it.
551
+
552
+ Floored at 1 rather than validated: context_limit() can only return a
553
+ positive number, and effective_compaction() raises on a trigger below
554
+ 1, so this exists to keep an absurd window from turning into a
555
+ confusing error two layers away from the value that caused it.
556
+
557
+ AND FLOORED AGAIN, above the dependent floors (TECHNICAL_DEBT 42).
558
+ Headroom's cap holds the trigger at 0.75*window down here, so a window
559
+ of 10,666 or less derives a trigger at or below warning_margin_tokens
560
+ and effective_compaction() raises -- on should_compact()'s path, which
561
+ runs at the top of every step, with both _maybe_compact call sites bare
562
+ `yield from`. Every turn on such a model died before the first model
563
+ call.
564
+
565
+ REACHED BY A PROVIDER, NOT BY A COMMAND, which is what the register
566
+ entry got wrong. /window refuses anything at or below the pipeline
567
+ backstop margin (20,000), which is stricter than 10,666 and covers that
568
+ route by coincidence; MODEL_CONTEXT_WINDOWS's smallest entry is 200,000
569
+ and DEFAULT_CONTEXT_WINDOW is 256,000. Source 1 -- what the provider
570
+ SAID -- has no guard at all, and 8,192 is the commonest real window a
571
+ self-hosted or gateway endpoint reports.
572
+
573
+ BELOW ~10,667 THIS STOPS BEING A DERIVATION, and that is said out loud
574
+ rather than left to be discovered. The returned value is the floor, not
575
+ 0.75*window, so the fraction no longer describes it. A derivation that
576
+ silently stops deriving is the drift class this record is full of; the
577
+ alternative was distrusting the provider's own number, which is a
578
+ larger claim for a smaller gain.
579
+
580
+ AND AT OR BELOW 8,000 IT STOPS BEING A TRIGGER, which is the step the
581
+ paragraph above did not take (batch 148). The floor is applied
582
+ with no reference to the window, so below itself it is simply larger
583
+ than the window and nothing can reach it. Measured: a 4,096-token
584
+ window derives 8,001 and should_compact() answers "warn" at every value
585
+ from 1 to 4,097 and "compact" at none of them. The value is unchanged --
586
+ _warn_if_the_floor_left_no_room above is the whole fix, because what was
587
+ missing was never a number.
588
+ """
589
+ window = context_limit(model, provider_name)
590
+ share = window - headroom_for(window)
591
+ floor = _dependent_floor()
592
+ trigger = max(1, share, floor)
593
+ _warn_if_the_floor_left_no_room(model, provider_name, window, share,
594
+ floor, trigger)
595
+ _warn_if_one_read_cannot_fit(model, provider_name, window, share, floor,
596
+ trigger)
597
+ return trigger
598
+
599
+
600
+ def _trigger_is_configured() -> bool:
601
+ """Whether settings.json names compaction.trigger_tokens.
602
+
603
+ The derived trigger is a DEFAULT, so it must not outrank a number a
604
+ human wrote in a config file -- and effective_compaction() cannot tell
605
+ a configured value from the config.py fallback, because it merges them
606
+ into one dict by design (TECHNICAL_DEBT item 12: the merge records no
607
+ provenance). Asking the settings directly is the narrow question this
608
+ one decision needs, rather than a provenance mechanism the rest of
609
+ that dict has done without.
610
+ """
611
+ return "trigger_tokens" in (config_loader.get_settings().get(
612
+ "compaction") or {})
613
+
614
+
615
+ def thresholds(model: str, mode: str = "working_set",
616
+ overrides: Optional[dict] = None,
617
+ provider_name: Optional[str] = None) -> tuple:
618
+ """(warn_at, compact_at) in tokens, for this mode.
619
+
620
+ TWO MODES, because a research pass and a chat turn want different
621
+ answers (M6). "working_set" is the ordinary one: compaction keeps the
622
+ thread inside a share of the model's window, so turns stay affordable
623
+ and keep their tool steps. "backstop" is what a pipeline pass gets --
624
+ it fires only just under the window, because a pass is headless and
625
+ unattended and each one already returns a distillation, so routine
626
+ compaction there would spend on a judgment call nobody is watching.
627
+ Since batch 44 both are derived from context_limit(); what still
628
+ separates them is how much room each leaves -- AND SINCE BATCH 148 the
629
+ backstop is ordered against the trigger rather than merely given a
630
+ bigger number, because "how much room each leaves" was answering the
631
+ question backwards below 200,000 (batch 148).
632
+
633
+ FOUR SOURCES FOR THE WORKING-SET TRIGGER, nearest first: an explicit
634
+ `overrides` (a `/compact --strength N`), a session `/trigger` bound to
635
+ this pair, settings.json's compaction.trigger_tokens, and the derived
636
+ share. The first three are absolute numbers a human named and all
637
+ outrank the derivation, which is what makes batch 44 a change of
638
+ DEFAULT rather than a removal of the control.
639
+ """
640
+ # Resolved HERE because this is the only place the working-set trigger
641
+ # is read and the only place that knows the model. effective_compaction
642
+ # stays model-agnostic, and D27's four-tier chain is unchanged -- both
643
+ # the session value and the derived default arrive through the existing
644
+ # per-invocation slot rather than adding a fifth tier. An explicit
645
+ # `overrides` still wins, since nearest is meant to win and the caller
646
+ # is nearer.
647
+ trigger = session.trigger_for(provider_name, model)
648
+ if trigger is None and mode != "backstop" and not _trigger_is_configured():
649
+ trigger = derived_trigger(model, provider_name)
650
+ if trigger is not None:
651
+ overrides = {"trigger_tokens": trigger, **(overrides or {})}
652
+ settings = config_loader.effective_compaction(overrides)
653
+ if mode == "backstop":
654
+ # ABOVE THE WORKING-SET TRIGGER, STRUCTURALLY (batch 148).
655
+ # "A last resort" is a statement about ORDER, and this was a flat
656
+ # 20,000-token margin while batch 44 made the ordinary trigger a
657
+ # clamped share -- so the backstop left MORE room than the trigger,
658
+ # that is fired EARLIER, at every window below 200,000. Measured:
659
+ # 4,000 tokens earlier at 64,000 and at 131,072, 11,808 earlier at
660
+ # 32,768, and at or below 20,001 the old max(1, ...) clamped it to 1,
661
+ # so every evaluation of every step of every pass asked compact().
662
+ # M6's argument -- a pass is headless and unattended, so routine
663
+ # compaction there spends on a judgment call nobody is watching --
664
+ # was inverted for most of the roster.
665
+ #
666
+ # THE SHIPPED TABLE IS WHY NOTHING CAUGHT IT: every entry is at or
667
+ # above 200,000, where the two numbers were equal or already in the
668
+ # right order. The inversion is invisible on the table and universal
669
+ # off it, and source 1 -- what a provider SAID -- is the way in.
670
+ #
671
+ # derived_trigger rather than the fully resolved working-set value:
672
+ # it cannot raise (see its floor), and M6 speaks about the derived
673
+ # default rather than about a number a human typed. A configured
674
+ # trigger high enough to still invert this is one that is itself
675
+ # near or above the window, and a reachable backstop under an
676
+ # unreachable trigger is the right way round.
677
+ compact_at = max(
678
+ derived_trigger(model, provider_name) + 1,
679
+ context_limit(model, provider_name)
680
+ - config.COMPACTION_PIPELINE_BACKSTOP_TOKENS)
681
+ return compact_at, compact_at
682
+ compact_at = settings["trigger_tokens"]
683
+ return compact_at - settings["warning_margin_tokens"], compact_at
684
+
685
+
686
+ def should_compact(used: int, model: str, mode: str = "working_set",
687
+ overrides: Optional[dict] = None,
688
+ provider_name: Optional[str] = None) -> str:
689
+ """"" | "warn" | "compact", from a measured context size.
690
+
691
+ `used` is ModelResponse.usage["input_tokens"] from the most recent
692
+ call -- the provider's own measurement of everything it was sent, which
693
+ is exact but retrospective. That is why the check runs AFTER a response
694
+ and acts before the next call.
695
+
696
+ D21 is what makes this work rather than pedantry: a streaming path that
697
+ silently reported zero usage would leave `used` at 0 forever, so
698
+ compaction would never fire and the harness would run into a hard
699
+ context-limit error from the provider instead. The budget stop
700
+ condition and this trigger fail together, from the same cause.
701
+ """
702
+ if _is_compacting():
703
+ return ""
704
+ warn_at, compact_at = thresholds(model, mode, overrides, provider_name)
705
+ if used >= compact_at:
706
+ return "compact"
707
+ if used >= warn_at:
708
+ return "warn"
709
+ return ""
710
+
711
+
712
+ def _sub_turn_span(rows, starts, settings, current_turn_start):
713
+ """A watermark INSIDE one turn, or None. Batch 120, register item 40.
714
+
715
+ THE LAST RESORT, reached only when no turn-aligned fold exists at all.
716
+ Batch 119 made the turn COUNT yield, which unsticks any thread with two
717
+ completed turns; what it could not reach is a thread whose only turn is
718
+ the one still running. The reported case was 142 rows and 168,311 proxy
719
+ tokens inside ONE turn: over the trigger, entirely unfoldable, and
720
+ answering `no-progress` on every evaluation forever.
721
+
722
+ WHAT THIS AMENDS, PRECISELY. M5 says the current turn is never foldable
723
+ because "a summary that swallowed the messages the model is reasoning
724
+ about right now would rewrite the question mid-answer." The reason is
725
+ right and it does not cover the whole turn: after forty-six steps the
726
+ model is not reasoning about step three's tool output, and what must
727
+ survive verbatim is the turn's own REQUEST plus the recent steps. Both
728
+ do. The opening user row is re-added by `pinned_through` (see its
729
+ docstring) and `keep_recent_tokens` of the tail is held back here, so
730
+ the question is never rewritten -- it is carried unchanged, with the
731
+ middle of the work folded between it and the recent steps.
732
+
733
+ M4 IS SATISFIED BY CONSTRUCTION, not by checking. Its rule is that a
734
+ fold must never separate an assistant message carrying `tool_calls`
735
+ from the `tool_result` rows answering them, because a `tool_result`
736
+ with no preceding `tool_use` is an HTTP 400 on Anthropic. Inside a turn
737
+ the archive is `user, (assistant, tool+)*` -- D20 persists the
738
+ assistant row before dispatch and the answering rows after it returns,
739
+ including every row of a parallel dispatch -- so **cutting immediately
740
+ before an assistant row leaves every earlier call answered.** Measured
741
+ on the reported thread: 47 assistant rows inside the turn, 46 candidate
742
+ boundaries, and 20 of its steps carry between 2 and 5 tool rows, which
743
+ is exactly why the boundary is the assistant row and not an arbitrary
744
+ position.
745
+
746
+ Returns None rather than a boundary when the turn holds fewer than two
747
+ steps. One step cannot be folded without folding all of it, and a turn
748
+ with no steps is a bare request.
749
+ """
750
+ index = (current_turn_start if current_turn_start is not None
751
+ else len(starts) - 1)
752
+ if not 0 <= index < len(starts):
753
+ return None
754
+ opener = starts[index]
755
+
756
+ steps = [i for i in range(opener + 1, len(rows))
757
+ if rows[i]["role"] == "assistant"]
758
+ if len(steps) < 2:
759
+ return None
760
+
761
+ # keep_recent_tokens of the tail, WHOLE STEPS at a time -- the same
762
+ # floor and the same character proxy the turn-aligned path uses, just
763
+ # counted over steps instead of turns, so the two cannot disagree about
764
+ # how much verbatim tail a thread is promised.
765
+ bounds = steps + [len(rows)]
766
+ kept = 0
767
+ cut = steps[-1]
768
+ for position in range(len(steps) - 1, 0, -1):
769
+ kept += sum(_row_chars(rows[i])
770
+ for i in range(bounds[position], bounds[position + 1]))
771
+ cut = steps[position]
772
+ if kept // CHARS_PER_TOKEN >= settings["keep_recent_tokens"]:
773
+ break
774
+
775
+ # A BACKSTOP, and it is unreachable: the loop stops at `steps[1]` at the
776
+ # earliest, so `cut` always exceeds `steps[0]` once there are two steps.
777
+ # Kept rather than argued away, for `pinned_through`'s reason one file
778
+ # over -- the failure it guards is a watermark that folds the request
779
+ # and nothing else, which is the one outcome here that would be wrong
780
+ # rather than merely unhelpful.
781
+ if cut <= steps[0]:
782
+ return None
783
+ return rows[cut - 1]["id"]
784
+
785
+
786
+ def compactable_span(memory, current_turn_start: Optional[int] = None,
787
+ overrides: Optional[dict] = None):
788
+ """The id of the last message that may be folded, or None if nothing
789
+ may be.
790
+
791
+ THREE FLOORS, AND THE EARLIEST WINS (M5) -- WITH ONE AMENDMENT, batch
792
+ 119, argued in full at the `preferred` line below:
793
+
794
+ * the current turn -- structural, never foldable at all. A summary
795
+ that swallowed the messages the model is reasoning about right now
796
+ would rewrite the question mid-answer. ABSOLUTE.
797
+ * keep_recent_tokens, the token floor §21 specifies. ABSOLUTE, and
798
+ it can be absolute safely because it is a SIZE: it holds exactly
799
+ what it says and then stops.
800
+ * the last N COMPLETED turns, verbatim. A single tool-heavy turn can
801
+ consume the whole keep-token budget by itself, leaving the
802
+ immediately preceding exchange summarized, and a follow-up like
803
+ "no, the other one" then has no referent. A PREFERENCE SINCE BATCH
804
+ 119: it is a COUNT, so it cannot tell three small turns from three
805
+ enormous ones, and it applies only while it still leaves something
806
+ foldable. Measured at 230k tokens held by `3 - 3 = 0` on a thread
807
+ 92.5% of which could have been folded.
808
+
809
+ So the guarantee this function makes is size-based rather than
810
+ count-based: the current turn verbatim, plus at least
811
+ keep_recent_tokens of completed turns verbatim, plus the last N
812
+ completed turns whenever that is affordable.
813
+
814
+ THE BOUNDARY IS ALWAYS A TURN START (M4). Every floor resolves to one,
815
+ so a fold can never separate an assistant message carrying tool_calls
816
+ from the tool results that answer them. That is not a quality concern:
817
+ a tool_result with no preceding tool_use is an HTTP 400 on Anthropic --
818
+ a hard wire error on the next call, on a thread that was working a
819
+ moment ago.
820
+
821
+ Returns None when the floors leave nothing, which is a real state and
822
+ not a failure: a thread of three enormous turns is over the trigger and
823
+ entirely protected. The caller reports it rather than silently doing
824
+ nothing.
825
+
826
+ EVERY FLOOR IS MEASURED IN ARCHIVE SPACE (M11), from one load of the
827
+ thread's rows. The keep-tokens floor used to slice `memory.messages`
828
+ and map positions back onto the archive's turn list; M8 puts a
829
+ `role: "user"` summary at the head of a compacted view, so the two
830
+ lists disagree by one turn and `current_turn_start` arrived in the
831
+ wrong space entirely. That was §21a's shipped defect -- the watermark
832
+ went backwards and the second compaction of a thread un-compacted it.
833
+ Reading everything from `rows` makes the mismatch unrepresentable
834
+ rather than merely fixed.
835
+ """
836
+ from storage import _ordered_rows
837
+
838
+ settings = config_loader.effective_compaction(overrides)
839
+ rows = _ordered_rows(memory.thread_id)
840
+ starts = [i for i, row in enumerate(rows) if row["role"] == "user"]
841
+ if not starts:
842
+ return None
843
+
844
+ # Every candidate boundary is "fold everything strictly before turn i".
845
+ # The floors each veto some suffix of the turn list; the surviving
846
+ # boundary is the earliest turn any of them still allows.
847
+ #
848
+ # The token floor: keep whole turns, walking back from the end, until
849
+ # keep_recent_tokens is covered. Sized from the persisted content,
850
+ # which is the same character proxy M10 uses everywhere else.
851
+ bounds = starts + [len(rows)]
852
+ kept = 0
853
+ token_cutoff = len(starts)
854
+ for index in range(len(starts) - 1, -1, -1):
855
+ kept += sum(_row_chars(rows[i])
856
+ for i in range(bounds[index], bounds[index + 1]))
857
+ token_cutoff = index
858
+ if kept // CHARS_PER_TOKEN >= settings["keep_recent_tokens"]:
859
+ break
860
+
861
+ # THE TWO FLOORS THAT CAN MEASURE WHAT THEY PROTECT, intersected first.
862
+ cutoff = token_cutoff
863
+ if current_turn_start is not None:
864
+ cutoff = min(cutoff, current_turn_start)
865
+
866
+ # ...and then keep_recent_turns, WHICH YIELDS RATHER THAN VETOES.
867
+ # Batch 119, and this is an amendment to M5 rather than a fix to a
868
+ # mistake in it.
869
+ #
870
+ # M5 names three floors and says the earliest wins. That is right for
871
+ # two of them, because only two can measure what they are holding:
872
+ #
873
+ # * the current turn is STRUCTURAL -- folding it would rewrite the
874
+ # question being answered -- and is never negotiable;
875
+ # * keep_recent_tokens is a SIZE, so it protects exactly as much as
876
+ # it says and then stops;
877
+ # * keep_recent_turns is a COUNT, and a count is blind. Three turns
878
+ # can be 2k tokens or 230k.
879
+ #
880
+ # Blind is harmless until the thread is over the trigger. Then it is
881
+ # the one floor that can hold EVERYTHING while claiming to hold "the
882
+ # last three exchanges" -- and at that point the alternative to folding
883
+ # is not "keep the recent turns", it is the provider refusing the next
884
+ # prompt. There is no context-overflow handler anywhere in core/, so
885
+ # nothing downstream recovers.
886
+ #
887
+ # MEASURED, on the owner-reported thread that produced this batch: 182
888
+ # rows, 729k chars, 230k tokens by the provider's own count, and
889
+ # exactly THREE user turns. `3 - 3 = 0`, cutoff < 1, blocked -- while
890
+ # the token floor on its own would have folded everything before turn 2:
891
+ # 168,564 proxy tokens, 92.5% of the thread, with the last completed
892
+ # turn and the current one untouched. A good fold existed and a turn
893
+ # count vetoed it: on every evaluation, through a switch to a 1M-window
894
+ # model (this function takes no model and never did), and through a
895
+ # restart (it reads the archive, which does not change). There was no
896
+ # way out of that state from inside the app.
897
+ #
898
+ # NOT A WALK-DOWN from 3 to 2 to 1 taking the first count that works.
899
+ # On that same thread `keep_recent_turns=2` yields cutoff 1, which folds
900
+ # turn 0's 253 tokens, writes a checkpoint, and then answers no-progress
901
+ # forever -- a compaction that succeeds, frees 0.1%, and leaves
902
+ # advances() permanently satisfied against a watermark that helped
903
+ # nothing. Yielding all the way to the size-aware floors is what makes
904
+ # the model call worth spending.
905
+ #
906
+ # Still guaranteed afterwards: the current turn verbatim, plus at least
907
+ # keep_recent_tokens of completed turns verbatim. A size-based promise,
908
+ # which is the right kind to make in answer to size pressure.
909
+ preferred = min(cutoff, len(starts) - settings["keep_recent_turns"])
910
+ if preferred >= 1:
911
+ cutoff = preferred
912
+ elif cutoff >= 1:
913
+ # A STANDING CONDITION, said once per thread (batch 221, #217).
914
+ # This runs once per compact(), which _maybe_compact calls after
915
+ # every step while the thread is over the trigger -- so at INFO it
916
+ # repeated per step for the life of the conversation, the shape #44
917
+ # took out of this module. The first time a thread yields says it;
918
+ # the rest are DEBUG, like the no-progress line that follows them.
919
+ level = (logging.DEBUG if memory.thread_id in _yield_logged
920
+ else logging.INFO)
921
+ _yield_logged.add(memory.thread_id)
922
+ logger.log(
923
+ level,
924
+ "Compaction on thread %s: keep_recent_turns=%d would have held "
925
+ "all %d turns and blocked every fold, so it yielded. The current "
926
+ "turn and keep_recent_tokens still hold.",
927
+ memory.thread_id, settings["keep_recent_turns"], len(starts))
928
+
929
+ # THE TURN-ALIGNED FOLD HAS TO BE WORTH A MODEL CALL, not merely legal.
930
+ # Batch 134, and this is the gate `cutoff < 1` used to be.
931
+ #
932
+ # `completed_turns()` is `len(turn_start_ids) - 1`, so it is at least 1
933
+ # for any thread with two user rows, and the token floor's loop assigns
934
+ # `token_cutoff = index` BEFORE testing -- so it stops at
935
+ # `len(starts) - 1` as soon as the last turn alone exceeds
936
+ # keep_recent_tokens. Between them, `cutoff` was >= 1 on every thread
937
+ # with a second user row, and the sub-turn path behind `cutoff < 1` was
938
+ # unreachable there. The boundary was then the best TURN-ALIGNED one,
939
+ # which on a thread whose current turn is almost all of it is the end of
940
+ # the first turn.
941
+ #
942
+ # MEASURED on one 40-step turn, with and without one short exchange in
943
+ # front of it:
944
+ #
945
+ # 40 steps, one user row SUB-TURN at row 73 folds 90.0%
946
+ # one exchange, then the same turn-aligned row 2 folds 0.0%
947
+ # two exchanges, then the same turn-aligned row 4 folds 0.1%
948
+ # five exchanges, then the same turn-aligned row 6 folds 0.1%
949
+ #
950
+ # And it was a DEAD END rather than a slow start, because the useless
951
+ # fold satisfies `advances()` permanently: every later evaluation
952
+ # answered `no-progress`, at `logger.debug`, with `kind=None` so
953
+ # `_maybe_compact` appended no notice -- nothing on screen while the
954
+ # thread ran toward the provider's limit, where `headroom_for`'s
955
+ # docstring says the loop retries the identical oversized prompt three
956
+ # times and the turn dies. A sweep of every legal
957
+ # keep_recent_tokens x keep_recent_turns pair reached a sub-turn
958
+ # boundary 0 times in 30 accepted settings.
959
+ #
960
+ # This is the trap item 39 names and says it avoided -- "a successful
961
+ # compaction that cannot be repeated" -- arriving on the DEFAULT
962
+ # configuration with no settings edit at all, and item 40's own measured
963
+ # scenario (two turns, 97.2% available) is the case the shipped gate
964
+ # excluded.
965
+ #
966
+ # THE FLOOR IS keep_recent_tokens, which is the thing the fold exists to
967
+ # make room behind: a boundary that frees less than the tail it must
968
+ # keep has not answered the size pressure it was called for. Below it,
969
+ # fall through to the sub-turn path exactly as `cutoff < 1` does -- and
970
+ # that branch is kept untouched, so the single-turn case batch 120 fixed
971
+ # is unchanged. `_sub_turn_span` itself needs nothing: with
972
+ # `current_turn_start >= 1` it already resolves `opener = starts[index]`
973
+ # to the current turn's user row and scans forward from there.
974
+ worth_it = True
975
+ if cutoff >= 1:
976
+ freed = sum(_row_chars(rows[i])
977
+ for i in range(starts[cutoff])) // CHARS_PER_TOKEN
978
+ worth_it = freed >= settings["keep_recent_tokens"]
979
+ if not worth_it:
980
+ logger.info(
981
+ "Compaction on thread %s: the turn-aligned boundary would "
982
+ "free %d proxy tokens against a keep_recent_tokens of %d, "
983
+ "which is not worth a model call, so the boundary is inside "
984
+ "the current turn instead.",
985
+ memory.thread_id, freed, settings["keep_recent_tokens"])
986
+
987
+ if cutoff < 1 or not worth_it:
988
+ # NO TURN-ALIGNED FOLD WORTH MAKING. Batch 120 tries one inside the
989
+ # turn before giving up -- see _sub_turn_span for what that costs
990
+ # and why M4 holds. Last, and only here: a turn-aligned boundary is
991
+ # always preferable WHEN IT FREES ENOUGH, since it needs no row
992
+ # re-added and no amendment to M5 at all.
993
+ inside = _sub_turn_span(rows, starts, settings, current_turn_start)
994
+ if inside is not None:
995
+ if cutoff < 1:
996
+ logger.info(
997
+ "Compaction on thread %s: no turn-aligned fold exists "
998
+ "(%d turns, all held), so the boundary is inside the "
999
+ "current turn. Its request and the recent steps stay "
1000
+ "verbatim.",
1001
+ memory.thread_id, len(starts))
1002
+ return inside
1003
+ # A sub-turn fold is not available either (fewer than two steps in
1004
+ # the current turn). A small turn-aligned fold still beats nothing,
1005
+ # so fall back to it rather than refusing to compact at all.
1006
+ if cutoff < 1:
1007
+ return None
1008
+ # Fold everything strictly before turn `cutoff`, so the watermark is
1009
+ # the row just before that turn's first row. cutoff >= 1 guarantees
1010
+ # there is one.
1011
+ return rows[starts[cutoff] - 1]["id"]
1012
+
1013
+
1014
+ def _target_chars(original_chars: int, strength: int) -> int:
1015
+ return int(original_chars * config.COMPACTION_TARGET_RATIOS[strength])
1016
+
1017
+
1018
+ def _instruction(segment_text: str, target: int, original: int) -> str:
1019
+ return (
1020
+ f"Summarize the conversation excerpt below.\n\n"
1021
+ f"The original is {original} characters. Your summary must be at "
1022
+ f"most {target} characters -- shorter is fine, longer will be "
1023
+ f"rejected.\n\n"
1024
+ f"--- BEGIN EXCERPT ---\n{segment_text}\n--- END EXCERPT ---"
1025
+ )
1026
+
1027
+
1028
+ def _as_text(messages) -> str:
1029
+ lines = []
1030
+ for message in messages:
1031
+ role = message.get("role", "?")
1032
+ if role == "assistant":
1033
+ body = message.get("text", "")
1034
+ calls = message.get("tool_calls") or []
1035
+ if calls:
1036
+ body = f"{body}\n[called: {', '.join(c.get('name', '?') for c in calls)}]"
1037
+ else:
1038
+ body = str(message.get("content", ""))
1039
+ # ROADMAP_v3 §49 (SS5). A user-role row the HARNESS wrote -- a
1040
+ # background session's result -- is not something the user said,
1041
+ # and a summary that attributed program output to them would be
1042
+ # M8's mistake one layer down.
1043
+ if message.get("harness"):
1044
+ role = "harness"
1045
+ lines.append(f"{role}: {body}")
1046
+ return "\n\n".join(lines)
1047
+
1048
+
1049
+ def pin_measurements(thread_id, last_n: int, model: Optional[str] = None,
1050
+ provider_name: Optional[str] = None) -> dict:
1051
+ """What #89's cap is measured against, in M10's character proxy.
1052
+
1053
+ Returns three numbers:
1054
+ requested_tokens what the last `last_n` turns' ARCHIVE rows cost --
1055
+ the span one more `pin(last_n)` would protect
1056
+ pinned_tokens everything ALREADY pinned on this thread
1057
+ max_tokens PIN_MAX_TRIGGER_FRACTION x the trigger that FIRES
1058
+
1059
+ Reads the ARCHIVE (the same rows compactable_span walks), so a pinned
1060
+ prefix is counted at full weight exactly as the derived view will
1061
+ carry it. Never compared against a provider count (M10).
1062
+
1063
+ THE PAIR IS OPTIONAL AND THE ANSWER DEPENDS ON IT (batch 148).
1064
+ #89's cap is a fraction OF THE TRIGGER, and since batch 44 the trigger
1065
+ that decides when a thread folds is derived per model -- so reading the
1066
+ configured number alone made the cap 20,000 for every model and both
1067
+ directions wrong. Measured against the trigger that actually fires:
1068
+ 250% of it on an 8,192-token window, where one pin could protect more
1069
+ than the whole trigger and floor the thread permanently above it, which
1070
+ is the state #89 exists to prevent; and 8% of it on a 262,144-token
1071
+ window, where `pin` refuses requests the stated policy allows. The
1072
+ value was unchanged by batch 44 and the PROPERTY was not, which is the
1073
+ marathon's shape 9, and AGENTS.md's "so #89's cap is unchanged" is the
1074
+ sentence that made it look settled.
1075
+
1076
+ The stated obstacle was real and is gone: this function had no
1077
+ (provider, model) to match a session override against, and
1078
+ `tools/builtin/pin.py` receives `parent_run` -- already in
1079
+ registry._INJECTABLE_PARAMS, already carrying both -- one declared
1080
+ parameter away. With the pair the trigger is resolved exactly as
1081
+ thresholds() resolves it, so a session `/trigger`, a configured one and
1082
+ the derivation all reach the cap through the chain that already exists.
1083
+ Without it the binding-free read below is the fallback, so nothing that
1084
+ calls this from outside a run moves.
1085
+ """
1086
+ from core import config_loader
1087
+ from storage import _ordered_rows
1088
+
1089
+ settings = config_loader.effective_compaction()
1090
+ # THE MINIMUM, and the min() is load-bearing rather than defensive.
1091
+ # With no (provider, model) to match a session override against, this
1092
+ # reads the binding-free one -- and takes whichever trigger is SMALLER,
1093
+ # which is safe under every binding. A raised session trigger leaves
1094
+ # the cap stricter than it needs to be; a lowered one pulls the cap
1095
+ # down with it. Reading the configured trigger alone would let
1096
+ # `/trigger 12k` leave this cap at 20k, so a pin could protect more
1097
+ # than the whole trigger and floor the thread permanently above it --
1098
+ # which is the exact defect #89 exists to prevent, reintroduced
1099
+ # through a number typed in a different command.
1100
+ trigger = min(settings["trigger_tokens"],
1101
+ session.trigger_any() or settings["trigger_tokens"])
1102
+ if model:
1103
+ try:
1104
+ trigger = thresholds(model, provider_name=provider_name)[1]
1105
+ except Exception: # noqa: BLE001 -- see below
1106
+ # _dependent_floor's posture, for the same reason: a cap that
1107
+ # cannot be computed must never become the reason a pin fails.
1108
+ # effective_compaction raises on an incoherent settings.json,
1109
+ # and the binding-free read above is still a cap.
1110
+ logger.debug(
1111
+ "Could not resolve the compaction trigger for %r on %r; "
1112
+ "measuring the pin cap against the configured trigger.",
1113
+ model, provider_name)
1114
+ max_tokens = int(config.PIN_MAX_TRIGGER_FRACTION * trigger)
1115
+
1116
+ rows = _ordered_rows(thread_id)
1117
+ starts = [i for i, row in enumerate(rows) if row["role"] == "user"]
1118
+ bounds = starts + [len(rows)]
1119
+
1120
+ def _tokens(lo: int) -> int:
1121
+ return sum(_row_chars(rows[i])
1122
+ for i in range(lo, len(rows))) // CHARS_PER_TOKEN
1123
+
1124
+ requested = _tokens(bounds[max(0, len(starts) - last_n)]) if starts else 0
1125
+ pinned = sum(_row_chars(row) for row in rows
1126
+ if row["pinned"]) // CHARS_PER_TOKEN
1127
+ return {
1128
+ "requested_tokens": requested,
1129
+ "pinned_tokens": pinned,
1130
+ "max_tokens": max_tokens,
1131
+ }
1132
+
1133
+
1134
+ def _truncate_oldest(text: str, budget: int) -> tuple:
1135
+ """`(text, notice)` -- drop the earliest characters over `budget`.
1136
+
1137
+ Returns the text unchanged and `None` when it already fits. The OLDEST
1138
+ material goes, because recent turns are the referent-heavy ones, and
1139
+ the cut is stated in the returned notice so both callers can put it in
1140
+ the instruction AND in the stored row.
1141
+
1142
+ ONE COPY, since batch 45. This was eight identical lines in `compact()`
1143
+ and in `summarize_thread()`, notice string included, marked as
1144
+ deliberate nowhere -- the shape
1145
+ `safety/policy_enforcement.param_digest` calls this project's canonical
1146
+ bug when it explains why the digest is not written twice. The two were
1147
+ equivalent only by accident: the second guarded on a separate
1148
+ `original` variable that happened to equal `len(thread_text)` at that
1149
+ point, so the condition and the arithmetic under it could have drifted
1150
+ apart without either copy looking wrong.
1151
+ """
1152
+ if len(text) // CHARS_PER_TOKEN <= budget:
1153
+ return text, None
1154
+ keep_chars = max(0, budget * CHARS_PER_TOKEN)
1155
+ dropped = len(text) - keep_chars
1156
+ notice = (f"[Source truncated: the earliest {dropped} characters were "
1157
+ f"not summarized.]")
1158
+ return f"{notice}\n{text[-keep_chars:]}", notice
1159
+
1160
+
1161
+ def _input_budget(model: str, provider_name: Optional[str] = None) -> int:
1162
+ """One-call INPUT ceiling for a summarizer prompt, in proxy tokens.
1163
+
1164
+ context_limit minus the pipeline backstop margin -- generous by
1165
+ construction, and honest about its weakness (M10): this compares the
1166
+ chars-per-token PROXY against a real window number, which every other
1167
+ comparison in this module refuses to do. The comparison is inherently
1168
+ approximate; what makes it safe is the failure direction. Undershooting
1169
+ the budget costs truncation, which is stated; overshooting it costs an
1170
+ oversized send, which is a provider error mid-compaction on exactly
1171
+ the thread that can least afford one.
1172
+ """
1173
+ return max(1_000, context_limit(model, provider_name)
1174
+ - config.COMPACTION_PIPELINE_BACKSTOP_TOKENS)
1175
+
1176
+
1177
+ def parse_compact_args(args: str) -> tuple:
1178
+ """(overrides, error). ROADMAP_v2 §21's per-invocation override --
1179
+ applies to this one run and persists nothing, which is the last step
1180
+ of D27's resolution order.
1181
+
1182
+ `/compact`'s grammar in either shell: both parse here, so one cannot
1183
+ accept a spelling the other refuses (ROADMAP_v3 §89; moved from
1184
+ tui/app.py).
1185
+
1186
+ An unrecognised flag is an ERROR, not something to ignore. Silently
1187
+ dropping `--strenght 4` would compact at the default strength while
1188
+ the user believes they asked for something else, and the result looks
1189
+ exactly like a compaction that obeyed them.
1190
+ """
1191
+ overrides: dict = {}
1192
+ tokens = args.split()
1193
+ index = 0
1194
+ while index < len(tokens):
1195
+ token = tokens[index]
1196
+ if token in ("--strength", "-s"):
1197
+ index += 1
1198
+ if index >= len(tokens):
1199
+ return None, "--strength needs a value from 1 to 5."
1200
+ try:
1201
+ overrides["strength"] = int(tokens[index])
1202
+ except ValueError:
1203
+ return None, f"--strength needs a number, got {tokens[index]!r}."
1204
+ elif token.startswith("--strength="):
1205
+ value = token.split("=", 1)[1]
1206
+ try:
1207
+ overrides["strength"] = int(value)
1208
+ except ValueError:
1209
+ return None, f"--strength needs a number, got {value!r}."
1210
+ else:
1211
+ return None, f"Unknown option {token!r}. Usage: /compact [--strength N]"
1212
+ index += 1
1213
+ return overrides, None
1214
+
1215
+
1216
+ def compact(memory, model: str, provider_name: str,
1217
+ current_turn_start: Optional[int] = None,
1218
+ overrides: Optional[dict] = None,
1219
+ authorization=None,
1220
+ activity=None, depth: int = 1) -> dict:
1221
+ """Compact `memory`'s thread. Returns an OUTCOME dict -- never None.
1222
+
1223
+ Batch 16 (#44) changed this contract. It used to return a notice dict
1224
+ on success and None on every other exit -- five flavors of "nothing
1225
+ happened" that were indistinguishable at the call site and logged by
1226
+ three different conventions (WARNING per evaluation, debug-only,
1227
+ nothing at all). Now every exit is data:
1228
+
1229
+ {"status": <one of the seven below>,
1230
+ "kind": <notice kind for the loop's per-run dedup, or None>,
1231
+ "text": <a human line both shells render>}
1232
+
1233
+ The seven statuses, which are this function's whole vocabulary:
1234
+
1235
+ folded a checkpoint was written (kind="compaction")
1236
+ blocked the keep floors protect everything
1237
+ all-pinned everything newly foldable is pinned (#89's silent
1238
+ path, named now)
1239
+ missing-agent the compactor definition is absent
1240
+ no-progress the fold boundary has not moved past the last
1241
+ checkpoint
1242
+ reentrant a compaction is already running in this process
1243
+ failed the compactor produced nothing usable
1244
+
1245
+ Three of them are STANDING CONDITIONS (blocked, all-pinned,
1246
+ missing-agent) and share one notice kind, so the loop's existing
1247
+ once-per-run dedup governs their WARNINGs too instead of each firing
1248
+ its own per-evaluation line. They are enumerated HERE, at the function
1249
+ that produces them, rather than in a module-level tuple: batch 16 kept
1250
+ a `COMPACTION_OUTCOMES` sequence beside this docstring and nothing ever
1251
+ read it, which is `CODE_STAGES`' shape exactly (see the note in
1252
+ core/reasoning/events.py) -- a list whose only future was drifting away
1253
+ from the call sites while looking like a contract.
1254
+
1255
+ REPORTABILITY LIVES WITH THE CALLER. How often this function runs --
1256
+ once at the turn boundary plus once after every step -- is run-scope
1257
+ knowledge the loop has and this module lacks, which is why the
1258
+ standing-condition WARNINGs moved out of it into _maybe_compact's
1259
+ once-per-run guard (#44). What remains here is mechanics: DEBUG for a
1260
+ fold boundary that did not move, and _summarize's own retry warnings,
1261
+ which are events about one model call rather than states of the run.
1262
+
1263
+ Runs the compactor as an ORDINARY AGENT through the same
1264
+ RunAgentLoop everything else uses. §21 is explicit that summarizing is
1265
+ the shape of an agent call -- a system prompt, a task, a judgment-based
1266
+ output -- and that routing it through the shared machinery is also what
1267
+ gives it real autonomy over WHAT to preserve. Mechanical truncation
1268
+ cannot exercise judgment at all.
1269
+
1270
+ The compactor's own run gets its own fresh thread, no tools
1271
+ (`allowed_tools: []` in its definition), and the re-entrancy guard, so
1272
+ it can neither call anything nor trigger a compaction of its own.
1273
+ """
1274
+ from agents.manager import manager
1275
+ from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop
1276
+ from storage import (
1277
+ advances,
1278
+ history_through,
1279
+ latest_checkpoint,
1280
+ save_checkpoint,
1281
+ )
1282
+ storage_advances = advances
1283
+
1284
+ if _is_compacting():
1285
+ return {"status": "reentrant", "kind": None,
1286
+ "text": "A compaction is already running."}
1287
+
1288
+ settings = config_loader.effective_compaction(overrides)
1289
+ watermark = compactable_span(memory, current_turn_start, overrides)
1290
+ if watermark is None:
1291
+ logger.debug(
1292
+ "Compaction wanted on thread %s but every message is protected "
1293
+ "by the keep floors; nothing folded.", memory.thread_id)
1294
+ return {
1295
+ "status": "blocked",
1296
+ "kind": "compaction_blocked",
1297
+ # TWO FALSE CLAIMS IN ONE LINE, both corrected in batch 119.
1298
+ #
1299
+ # "Context is full" -- it is not. The trigger is a fraction of
1300
+ # the window, so this is read with the headroom still unspent,
1301
+ # and the owner who reported it reasonably concluded the harness
1302
+ # treats the window and the trigger as one number. The usage
1303
+ # line showing the TRIGGER as its only denominator is the other
1304
+ # half of that impression; batch 119 fixes both.
1305
+ #
1306
+ # "the most recent turns fill it entirely" -- names SIZE, and
1307
+ # what actually blocked the one reported occurrence was a turn
1308
+ # COUNT on a thread 92.5% of which was foldable. The single
1309
+ # diagnostic this message offered pointed away from its cause,
1310
+ # which is worse than offering none.
1311
+ "text": ("Over the compaction trigger, but every turn is held "
1312
+ "by the keep floors -- nothing could be folded. The "
1313
+ "thread keeps running uncompacted; a fold becomes "
1314
+ "possible once this turn completes."),
1315
+ }
1316
+
1317
+ agent = manager.get(config.COMPACTOR_AGENT)
1318
+ if agent is None:
1319
+ logger.debug(
1320
+ "Compaction wanted but the %r agent is not available.",
1321
+ config.COMPACTOR_AGENT)
1322
+ return {
1323
+ "status": "missing-agent",
1324
+ "kind": "compaction_blocked",
1325
+ "text": (f"The {config.COMPACTOR_AGENT!r} agent is not "
1326
+ f"available, so this conversation cannot be "
1327
+ f"condensed."),
1328
+ }
1329
+
1330
+ previous = latest_checkpoint(memory.thread_id)
1331
+ # NO PROGRESS, NO CALL. A watermark at or before the existing one means
1332
+ # the floors have not moved past what is already summarized -- there is
1333
+ # nothing new to fold. Checked HERE rather than only in save_checkpoint
1334
+ # because the model call happens in between: without it, rederive would
1335
+ # re-summarize a span it has already summarized, and chain would be
1336
+ # handed an empty segment and summarize its own previous summary,
1337
+ # degrading it a little on every attempt. Both spend a real call to
1338
+ # achieve nothing.
1339
+ if previous is not None and not storage_advances(
1340
+ memory.thread_id, previous["covers_up_to_message_id"], watermark):
1341
+ logger.debug(
1342
+ "Compaction wanted on thread %s but the fold boundary has not "
1343
+ "moved past the last checkpoint; nothing to do.", memory.thread_id)
1344
+ return {"status": "no-progress", "kind": None,
1345
+ "text": "Nothing new to fold since the last summary."}
1346
+
1347
+ # M2 as amended by batch 16 (#90). Re-derive from the archive by
1348
+ # default WHEN CONFIGURED; chain summarizes the previous summary plus
1349
+ # the tail. Whichever is configured, a span that outgrows one call
1350
+ # falls back to chain (verbose -- see the WARNING below), and one that
1351
+ # outgrows it even chained truncates its oldest material with the
1352
+ # truncation stated twice: to the model in the instruction, and in the
1353
+ # stored summary every later turn reads.
1354
+ chaining = settings["strategy"] == "chain" and previous is not None
1355
+
1356
+ def _build(chain_mode: bool):
1357
+ lower = previous["covers_up_to_message_id"] if chain_mode else None
1358
+ seg = history_through(memory.thread_id, watermark,
1359
+ after_message_id=lower)
1360
+ text = _as_text(seg)
1361
+ if chain_mode:
1362
+ text = ("Summary of everything before this point:\n"
1363
+ f"{previous['summary_text']}\n\n{text}")
1364
+ return seg, text
1365
+
1366
+ segment, segment_text = _build(chaining)
1367
+ if not segment:
1368
+ # Everything newly foldable is pinned (#89). This used to be the
1369
+ # one silent no-progress path -- indistinguishable, at every
1370
+ # level, from "nothing needed doing" -- while the state it reports
1371
+ # is exactly what compaction_blocked's text describes, reached by
1372
+ # another door. Named now, and worded so the reader knows the way
1373
+ # out.
1374
+ #
1375
+ # ON THE SEGMENT, NOT ON THE STRATEGY (batch 148). This
1376
+ # read `if not segment and not chaining:` from the day it was
1377
+ # written, and `chaining` is true under the SHIPPED
1378
+ # `compaction_strategy: chain` whenever a checkpoint exists -- so
1379
+ # the default strategy fell straight through the branch built for
1380
+ # this state. What it fell into is the harm the no-progress guard
1381
+ # twenty lines above names as its own reason: "chain would be
1382
+ # handed an empty segment and summarize its own previous summary,
1383
+ # degrading it a little on every attempt". That guard catches a
1384
+ # watermark that has not MOVED; it cannot catch a watermark that
1385
+ # moved across a region which is entirely pinned, because the
1386
+ # boundary genuinely advanced. This branch is the guard for that
1387
+ # case and the strategy test removed the default from its cover.
1388
+ #
1389
+ # Measured through the real compact() with three pinned turns in a
1390
+ # ten-turn thread: the compactor was handed exactly
1391
+ # "Summary of everything before this point:\n<previous summary>\n\n"
1392
+ # and nothing else, at a 379-character target, and the stored
1393
+ # checkpoint went from 2,489 characters to 23 -- reported as
1394
+ # status="folded", kind="compaction", "0 earlier messages compacted
1395
+ # into a summary". A success line for a durable 99% loss, and it
1396
+ # compounds geometrically on every repeat.
1397
+ #
1398
+ # EMPTY MEANS PINNED, exactly: history_through excludes pinned rows
1399
+ # (§21 AC2) and excludes nothing else, so an empty segment on a
1400
+ # watermark that advanced is this state and no other. The message
1401
+ # is therefore as true under chain as under rederive, and an
1402
+ # explicit /compact is refused here for the same reason the
1403
+ # no-progress guard refuses one -- degrading a summary is not a
1404
+ # tighter compaction of it.
1405
+ return {
1406
+ "status": "all-pinned",
1407
+ "kind": "compaction_blocked",
1408
+ "text": ("Context is full, but everything foldable is pinned. "
1409
+ "Unpin something with /unpin, or let more unpinned "
1410
+ "turns accumulate."),
1411
+ }
1412
+
1413
+ original = len(segment_text)
1414
+ target = _target_chars(original, settings["strength"])
1415
+
1416
+ # M2's automatic fallback, built at last after three documents
1417
+ # promised it for two sections. Forced only when there IS a previous
1418
+ # summary to chain onto; VERBOSE because a configured strategy
1419
+ # quietly doing the other thing is exactly what "(traced)" in the
1420
+ # spec was about.
1421
+ budget = _input_budget(model, provider_name)
1422
+ forced_chain_note = ""
1423
+ if (not chaining and previous is not None
1424
+ and len(segment_text) // CHARS_PER_TOKEN > budget):
1425
+ logger.warning(
1426
+ "Compaction on thread %s: the rederive span is ~%s tokens "
1427
+ "against a %s-token one-call budget; forcing chain onto the "
1428
+ "previous summary.",
1429
+ memory.thread_id, len(segment_text) // CHARS_PER_TOKEN, budget)
1430
+ chaining = True
1431
+ segment, segment_text = _build(True)
1432
+ original = len(segment_text)
1433
+ target = _target_chars(original, settings["strength"])
1434
+ forced_chain_note = (" Chained onto the previous summary because "
1435
+ "the span outgrew one call.")
1436
+
1437
+ # Still over -- or no previous summary existed to chain onto. Truncate
1438
+ # the OLDEST material (recent turns are the referent-heavy ones) and
1439
+ # state the cut in both places the summary travels.
1440
+ segment_text, truncation_notice = _truncate_oldest(segment_text, budget)
1441
+ if truncation_notice:
1442
+ # Both, as the forced-chain branch above does (#216, batch 213).
1443
+ # The target used to stay the untruncated length's, so the
1444
+ # instruction named one length and capped against another, and
1445
+ # the strength the user set came out looser by their ratio.
1446
+ original = len(segment_text)
1447
+ target = _target_chars(original, settings["strength"])
1448
+
1449
+ _set_compacting(True)
1450
+ try:
1451
+ # Batch 59. ONE span over the whole call, retries included: this is
1452
+ # one compactor run that may take several calls to hit its target,
1453
+ # and a shell drawing a row per attempt would report the retry loop
1454
+ # as a stack of compactors. Inside the re-entrancy guard rather
1455
+ # than around it, so the two brackets nest instead of interleaving.
1456
+ with agent_activity.span(activity, agent.name, depth):
1457
+ summary = _summarize(
1458
+ RunAgentLoop, manager, agent, DEFAULT_SYSTEM_PROMPT,
1459
+ segment_text, target, original, model, provider_name,
1460
+ settings["max_retries"], authorization,
1461
+ # §47. The compactor already had a span; what it did not
1462
+ # have was a way to say WHOSE conversation it is
1463
+ # summarising. It is a child of that thread in the only
1464
+ # sense that matters -- the summary is of it -- so the
1465
+ # link is not a convention, it is what happened.
1466
+ parent_thread_id=memory.thread_id)
1467
+ finally:
1468
+ _set_compacting(False)
1469
+
1470
+ if summary is None:
1471
+ # #136, batch 20: this used to be kind=None -- invisible to both
1472
+ # shells -- while its own WARNING fired inside _summarize on every
1473
+ # evaluation. A compactor that returned nothing IS a failed
1474
+ # compaction (AGENTS.md's containment rule says so), so it now
1475
+ # rides compaction_failed: visible once per run through the loop's
1476
+ # dedup, and the latch in _maybe_compact stops the per-step model
1477
+ # calls the silence was hiding.
1478
+ return {"status": "failed", "kind": "compaction_failed",
1479
+ "text": "The compactor returned nothing usable."}
1480
+
1481
+ if truncation_notice is not None:
1482
+ # Deterministic rather than trusted from the model's compliance:
1483
+ # the marker rides on the STORED summary, so the derived view --
1484
+ # and everyone reading it later -- sees the cut even if the model
1485
+ # never mentioned it.
1486
+ summary = f"{summary}\n\n{truncation_notice}"
1487
+
1488
+ strategy = "chain" if chaining else "rederive"
1489
+ save_checkpoint(memory.thread_id, summary, watermark, strategy)
1490
+ memory.apply_checkpoint()
1491
+ folded = len(segment)
1492
+ logger.info("Compacted thread %s: %s messages -> %s chars (%s).",
1493
+ memory.thread_id, folded, len(summary), strategy)
1494
+ return {
1495
+ "status": "folded",
1496
+ "kind": "compaction",
1497
+ "text": f"{folded} earlier messages compacted into a summary"
1498
+ + forced_chain_note,
1499
+ }
1500
+
1501
+
1502
+ def summarize_thread(thread_id, model: str, provider_name: str,
1503
+ overrides: Optional[dict] = None,
1504
+ authorization=None,
1505
+ activity=None, depth: int = 1) -> Optional[dict]:
1506
+ """Distil a WHOLE thread into a stored summary (ROADMAP_v2 §21c).
1507
+
1508
+ Returns a notice dict carrying the summary, or None if the thread has
1509
+ nothing in it. The shape matches compact()'s notices, so both shells
1510
+ render it with code they already have.
1511
+
1512
+ THIS IS NOT A COMPACTION and must never become one. compact() folds a
1513
+ span of the thread it is given, changing what the model sees on the next
1514
+ turn; this reads a thread and writes a description of it, leaving the
1515
+ thread untouched -- which is what lets `/ref` inject one thread's summary
1516
+ into a different thread, and what lets `/summary` show one without
1517
+ quietly shortening the conversation the user is having (M20).
1518
+
1519
+ THE ARCHIVE, NEVER THE DERIVED VIEW. `archive_history` returns every
1520
+ message ever written, so a summary of a compacted thread describes the
1521
+ conversation rather than describing the summary of it. A view-based
1522
+ version would degrade a little on every compaction, exactly the chaining
1523
+ loss M2 arranges the fold to avoid.
1524
+
1525
+ CACHED, AND STALENESS IS DETECTED RATHER THAN ASSUMED. The stored row
1526
+ carries the last archive position it accounts for, so `advances()` --
1527
+ which already answers "has this thread moved past that point?" for
1528
+ compaction -- says whether the summary still holds. An unchanged thread
1529
+ therefore costs no model call however many times it is referenced, and a
1530
+ grown one is re-summarized rather than silently served stale.
1531
+
1532
+ A THREAD ALREADY SHORTER THAN THE TARGET IS NOT SENT TO A MODEL. Its
1533
+ rendered text IS its own best summary, and asking a model to compress
1534
+ three messages into more characters than they occupy spends a call to
1535
+ make the answer worse. Same instinct as compact()'s no-progress-no-call
1536
+ guard.
1537
+
1538
+ The target is an ABSOLUTE character budget (`config.SUMMARY_TARGET_CHARS`),
1539
+ not `_target_chars`' strength ratio. A ratio is right for a fold, where
1540
+ the summary replaces the span it came from and scales with it. It is wrong
1541
+ here: §21c's consumer is a prompt tier present on EVERY turn of the
1542
+ referencing thread, so a proportional target would let one big thread
1543
+ inject tens of kilobytes into every call indefinitely.
1544
+ """
1545
+ from agents.manager import manager
1546
+ from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop
1547
+ from storage import (
1548
+ advances,
1549
+ archive_history,
1550
+ last_message_id,
1551
+ latest_thread_summary,
1552
+ save_thread_summary,
1553
+ )
1554
+
1555
+ if _is_compacting():
1556
+ return None
1557
+
1558
+ watermark = last_message_id(thread_id)
1559
+ if watermark is None:
1560
+ return None
1561
+
1562
+ existing = latest_thread_summary(thread_id)
1563
+ if existing is not None and not advances(
1564
+ thread_id, existing["covers_up_to_message_id"], watermark):
1565
+ return {
1566
+ "kind": "thread_summary",
1567
+ "text": existing["summary_text"],
1568
+ "thread_id": str(thread_id),
1569
+ "fresh": False,
1570
+ }
1571
+
1572
+ thread_text = _as_text(archive_history(thread_id))
1573
+ original = len(thread_text)
1574
+ target = config.SUMMARY_TARGET_CHARS
1575
+
1576
+ if original <= target:
1577
+ save_thread_summary(thread_id, thread_text, watermark)
1578
+ return {
1579
+ "kind": "thread_summary",
1580
+ "text": thread_text,
1581
+ "thread_id": str(thread_id),
1582
+ "fresh": True,
1583
+ "verbatim": True,
1584
+ }
1585
+
1586
+ # #90's gate on the second consumer. A thread summary's input is
1587
+ # bounded by NOTHING else -- compact()'s span at least waits for a
1588
+ # threshold -- and T4 documents what tool rows weigh. Reserve room for
1589
+ # the summary this call is meant to PRODUCE, then truncate the oldest
1590
+ # material with the cut stated in the instruction AND in the stored
1591
+ # row, so every referencing thread sees it.
1592
+ budget = max(1_000, _input_budget(model, provider_name)
1593
+ - config.SUMMARY_TARGET_CHARS // CHARS_PER_TOKEN)
1594
+ thread_text, truncation_notice = _truncate_oldest(thread_text, budget)
1595
+ if truncation_notice:
1596
+ original = len(thread_text)
1597
+
1598
+ agent = manager.get(config.COMPACTOR_AGENT)
1599
+ if agent is None:
1600
+ logger.warning(
1601
+ "A thread summary was wanted but the %r agent is not available; "
1602
+ "skipped.", config.COMPACTOR_AGENT)
1603
+ return None
1604
+
1605
+ settings = config_loader.effective_compaction(overrides)
1606
+ # The guard for the same reason compact() sets it (M3): the compactor is
1607
+ # an agent, so summarizing runs the loop, which evaluates the compaction
1608
+ # trigger. Its own thread is one turn long and would not trip it today,
1609
+ # which is exactly the kind of "cannot happen yet" that stops being true
1610
+ # quietly.
1611
+ _set_compacting(True)
1612
+ try:
1613
+ # Batch 59, and see compact() above for why one span covers the
1614
+ # retries. §21c's /summary runs this from its own worker, so it is
1615
+ # the one compactor run with no parent turn under it.
1616
+ with agent_activity.span(activity, agent.name, depth):
1617
+ summary = _summarize(
1618
+ RunAgentLoop, manager, agent, DEFAULT_SYSTEM_PROMPT,
1619
+ thread_text, target, original, model, provider_name,
1620
+ settings["max_retries"], authorization)
1621
+ finally:
1622
+ _set_compacting(False)
1623
+
1624
+ if summary is None:
1625
+ return None
1626
+
1627
+ if truncation_notice is not None:
1628
+ # Same determinism rule as compact(): the marker rides on the
1629
+ # stored row regardless of whether the model mentioned the cut.
1630
+ summary = f"{summary}\n\n{truncation_notice}"
1631
+
1632
+ save_thread_summary(thread_id, summary, watermark)
1633
+ logger.info("Summarized thread %s: %s chars -> %s.",
1634
+ thread_id, original, len(summary))
1635
+ return {
1636
+ "kind": "thread_summary",
1637
+ "text": summary,
1638
+ "thread_id": str(thread_id),
1639
+ "fresh": True,
1640
+ }
1641
+
1642
+
1643
+ def _summarize(loop_cls, manager, agent, base_prompt, segment_text, target,
1644
+ original, model, provider_name, max_retries, authorization,
1645
+ parent_thread_id=None):
1646
+ """Run the compactor, retrying while the summary overshoots its target.
1647
+
1648
+ STRUCTURALLY §3's JSON-retry loop with a length constraint in place of
1649
+ a parse -- a corrective follow-up into the SAME thread, so the model
1650
+ sees its own output and can tighten it, bounded by a retry cap.
1651
+ Deliberately not routed through core/reasoning/json_retry.py: that
1652
+ module is pipeline-shaped (it takes a run trace and names passes), and
1653
+ bending it to serve memory would invert the dependency for three lines
1654
+ of shared structure.
1655
+
1656
+ UNDERSHOOTING IS NOT AN ERROR. A summary tighter than asked for has
1657
+ already done the job, and rejecting it would spend a second model call
1658
+ to make the context bigger.
1659
+
1660
+ A summary still too long after the last retry is USED ANYWAY, with a
1661
+ warning. It is smaller than what it replaces, which is the whole point;
1662
+ discarding it would spend the calls and keep the full history, leaving
1663
+ the thread exactly as stuck as before with less budget to fix it.
1664
+ """
1665
+ from core.loop import advertisement_facts
1666
+
1667
+ context = manager.active_context(agent)
1668
+ # #228: the catalogs this prompt carries are decided by the run it is
1669
+ # for, through the bundle that run is given below -- the reviewer's
1670
+ # rule (core/reasoning/review.py). With system_prompt_for's attended
1671
+ # defaults this was right only while compactor.md's empty
1672
+ # allowed_tools kept both catalog tools out; a widening would have
1673
+ # reopened #68 on every automatic compaction of a headless run.
1674
+ callable_only, granted = advertisement_facts(authorization)
1675
+ system_prompt = manager.system_prompt_for(
1676
+ agent, base_prompt, context=context,
1677
+ callable_only=callable_only, granted=granted)
1678
+ tolerance = int(target * (1 + config.COMPACTION_RATIO_TOLERANCE))
1679
+
1680
+ response = loop_cls.run_agent_conversation(
1681
+ user_goal=_instruction(segment_text, target, original),
1682
+ model=agent.model or model,
1683
+ provider_name=agent.provider or provider_name,
1684
+ max_steps=1,
1685
+ context=context,
1686
+ system_prompt=system_prompt,
1687
+ authorization=authorization,
1688
+ # §27, and NOT in that section's spec: the compactor is a fifth
1689
+ # thread source nobody had counted. Every automatic compaction of a
1690
+ # long chat creates one of these, so on exactly the threads §21a
1691
+ # exists to serve, the picker filled up with the machinery that
1692
+ # served them. The compactor is an agent, so it is labelled like the
1693
+ # other agent-shaped runs.
1694
+ thread_kind=THREAD_KIND_SUBAGENT,
1695
+ # §47. No parent CALL -- no tool started this -- so the run is
1696
+ # findable by the conversation it belongs to and by nothing
1697
+ # else, which is the honest shape for a thread the harness
1698
+ # opened on its own initiative.
1699
+ thread_parent=parent_thread_id,
1700
+ thread_agent=agent.name,
1701
+ )
1702
+ summary = (response.text or "").strip()
1703
+
1704
+ for _ in range(max_retries):
1705
+ if not summary:
1706
+ logger.warning("Compactor returned nothing; compaction skipped.")
1707
+ return None
1708
+ if len(summary) <= tolerance:
1709
+ return summary
1710
+ response = loop_cls.continue_conversation(
1711
+ thread_id=response.thread_id,
1712
+ message=(
1713
+ f"That summary is {len(summary)} characters; the target is "
1714
+ f"{target}. Tighten it -- drop the least important material "
1715
+ f"rather than making the remaining facts vaguer. Output only "
1716
+ f"the summary."),
1717
+ system_prompt=system_prompt,
1718
+ model=agent.model or model,
1719
+ provider_name=agent.provider or provider_name,
1720
+ max_steps=1,
1721
+ context=context,
1722
+ authorization=authorization,
1723
+ )
1724
+ summary = (response.text or "").strip()
1725
+
1726
+ if not summary:
1727
+ logger.warning("Compactor returned nothing; compaction skipped.")
1728
+ return None
1729
+ if len(summary) > tolerance:
1730
+ logger.warning(
1731
+ "Compactor missed its target after %s retries (%s chars against a "
1732
+ "target of %s); using it anyway -- it is still smaller than the "
1733
+ "%s characters it replaces.", max_retries, len(summary), target,
1734
+ original)
1735
+ return summary