Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(learn): keep the digest's loop section inside its budget (#4269)

gglucass506ba16c4a7f
diff --git a/headroom/learn/analyzer.py b/headroom/learn/analyzer.py
index dd8fe0939..7cda57ca5 100644
--- a/headroom/learn/analyzer.py
+++ b/headroom/learn/analyzer.py
@@ -336,8 +336,9 @@ def _is_prompt_too_long(exc: Exception) -> bool:
Matches the known phrasings across backends: claude CLI ("Prompt is too
long"), Anthropic via LiteLLM ("prompt is too long: N tokens > M maximum"),
- OpenAI ("context_length_exceeded" / "maximum context length"), and Gemini
- ("input token count exceeds the maximum").
+ OpenAI ("context_length_exceeded" / "maximum context length"), Gemini
+ ("input token count exceeds the maximum"), and the codex CLI ("Input exceeds
+ the maximum length of 1048576 characters").
"""
msg = str(exc).lower()
return any(
@@ -348,6 +349,7 @@ def _is_prompt_too_long(exc: Exception) -> bool:
"maximum context length",
"context window",
"token count exceeds",
+ "input exceeds the maximum length",
)
)
@@ -392,30 +394,42 @@ def _build_digest(
lines.append(f"Tokens used: {total_tokens_in:,} in / {total_tokens_out:,} out")
lines.append("")
- # Detected loops first — the most expensive waste pattern, so the LLM sees
- # it before the (budget-truncatable) per-session event stream.
- loop_section = format_loops_for_digest(loops)
- if loop_section:
- lines.append(loop_section)
+ # Budget tracking — stop adding events when we approach the limit
+ # Rough estimate: 4 chars per token
+ char_budget = max_tokens * 4
+ # Every line costs its length plus the newline joining it, and goes in only
+ # if it leaves this room for the truncation markers that can follow it (an
+ # events line, a blank, a sessions line), so the digest stays inside
+ # char_budget. Only a prior-patterns section that leaves no such room on
+ # its own (never cut, see below) can push it past.
+ room = char_budget - 100
# Prior learned patterns (if any) — gives the LLM the current baseline so
# it can produce complete updated sections instead of condensed deltas.
+ # Never cut: a re-emitted section replaces its prior one wholesale, so a
+ # partial baseline would drop the missing bullets from the written file.
prior_section = _build_prior_patterns_section(project)
+
+ # Detected loops first — the most expensive waste pattern, so the LLM sees
+ # it before the (budget-truncatable) per-session event stream. The event
+ # stream cannot trim a section placed ahead of it, so the loops get their
+ # own cap: a quarter of the budget, less whatever the header and prior
+ # patterns leave short. Rendered whole, every loop with every index, the
+ # section alone outgrew the digest on a machine with years of Codex
+ # sessions, which learn scans as one project.
+ pre_event_chars = sum(len(ln) + 1 for ln in lines) + len(prior_section) + 2
+ loop_section = format_loops_for_digest(
+ loops, max_chars=min(char_budget // 4, room - pre_event_chars)
+ )
+ if loop_section:
+ lines.append(loop_section)
if prior_section:
lines.append(prior_section)
- # Budget tracking — stop adding events when we approach the limit
- # Rough estimate: 4 chars per token
- char_budget = max_tokens * 4
- chars_used = sum(len(ln) for ln in lines)
+ chars_used = sum(len(ln) + 1 for ln in lines)
+ full = False
for session in sessions:
- if chars_used > char_budget:
- lines.append(
- f"... (remaining {len(sessions) - sessions.index(session)} sessions truncated)"
- )
- break
-
session_header = (
f"=== Session {session.session_id[:12]} "
f"({len(session.tool_calls)} calls, {session.failure_count} failures"
@@ -423,29 +437,38 @@ def _build_digest(
if session.total_input_tokens:
session_header += f", {session.total_input_tokens:,} input tokens"
session_header += ") ==="
+ if full or chars_used + len(session_header) + 1 > room:
+ lines.append(
+ f"... (remaining {len(sessions) - sessions.index(session)} sessions truncated)"
+ )
+ break
lines.append(session_header)
- chars_used += len(session_header)
+ chars_used += len(session_header) + 1
# Use events if available (richer context), fall back to tool_calls
if session.events:
for event in session.events:
- if chars_used > char_budget:
+ event_line = _format_event(event)
+ if not event_line:
+ continue
+ if chars_used + len(event_line) + 1 > room:
lines.append(" ... (remaining events truncated)")
+ full = True
break
- event_line = _format_event(event)
- if event_line:
- lines.append(event_line)
- chars_used += len(event_line)
+ lines.append(event_line)
+ chars_used += len(event_line) + 1
else:
for tc in session.tool_calls:
- if chars_used > char_budget:
+ tc_line = _format_tool_call(tc)
+ if chars_used + len(tc_line) + 1 > room:
lines.append(" ... (remaining calls truncated)")
+ full = True
break
- tc_line = _format_tool_call(tc)
lines.append(tc_line)
- chars_used += len(tc_line)
+ chars_used += len(tc_line) + 1
lines.append("")
+ chars_used += 1
return "\n".join(lines)
diff --git a/headroom/learn/loops.py b/headroom/learn/loops.py
index f2949fd18..7595181c5 100644
--- a/headroom/learn/loops.py
+++ b/headroom/learn/loops.py
@@ -69,6 +69,11 @@ _PAGINATION_RE = re.compile("|".join(_PAGINATION_PATTERNS), re.IGNORECASE)
# otherwise identical commands do not split a loop into singletons.
_INT_RE = re.compile(r"\b\d+\b")
+# A loop's digest line shows its sample input cut to this many chars and its
+# first _DIGEST_MAX_INDICES message indices beside its full repeat count.
+_SAMPLE_INPUT_CHARS = 120
+_DIGEST_MAX_INDICES = 20
+
@dataclass
class LoopPattern:
@@ -290,7 +295,7 @@ def detect_loops(
LoopPattern(
tool=calls[0].name,
signature=_fuzzy_signature(signatures[key]),
- sample_input=calls[0].input_summary[:120],
+ sample_input=calls[0].input_summary[:_SAMPLE_INPUT_CHARS],
count=count,
is_error_loop=is_error_loop,
wasted_tokens=wasted,
@@ -302,15 +307,19 @@ def detect_loops(
return loops
-def format_loops_for_digest(loops: list[LoopPattern]) -> str:
+def format_loops_for_digest(loops: list[LoopPattern], max_chars: int | None = None) -> str:
"""Render detected loops as a high-priority digest section for the LLM.
- Returns "" when there are no loops so the digest is unchanged in the
- common case.
+ Loops are rendered in the given order (detect_loops sorts them costliest
+ first). With *max_chars*, rendering stops at the first loop that would
+ take the section past that many chars, so the costliest ones are kept.
+
+ Returns "" when there are no loops, or none fits, so the digest is
+ unchanged in the common case.
"""
if not loops:
return ""
- lines = [
+ header = [
"=== Detected Loops (HIGHEST PRIORITY) ===",
(
"These tool-call patterns REPEATED within a session — the most "
@@ -321,14 +330,21 @@ def format_loops_for_digest(loops: list[LoopPattern]) -> str:
),
"",
]
+ used = sum(len(ln) + 1 for ln in header) # each line plus its newline
+ entries: list[str] = []
for lp in loops:
- lines.append(
- f'- [{lp.kind}] {lp.tool}: "{lp.sample_input}" '
+ entry = (
+ f'- [{lp.kind}] {lp.tool}: "{lp.sample_input[:_SAMPLE_INPUT_CHARS]}" '
f"repeated {lp.count}x, ~{lp.wasted_tokens:,} tokens wasted "
- f"(messages {lp.msg_indices})"
+ f"(messages {lp.msg_indices[:_DIGEST_MAX_INDICES]})"
)
- lines.append("")
- return "\n".join(lines)
+ used += len(entry) + 1
+ if max_chars is not None and used > max_chars:
+ break
+ entries.append(entry)
+ if not entries:
+ return ""
+ return "\n".join([*header, *entries, ""])
def _signature_tokens(signature: str) -> set[str]:
diff --git a/tests/test_learn/test_analyzer.py b/tests/test_learn/test_analyzer.py
index d4a6d6498..6d1647abb 100644
--- a/tests/test_learn/test_analyzer.py
+++ b/tests/test_learn/test_analyzer.py
@@ -475,11 +475,22 @@ class TestSessionAnalyzer:
assert result.recommendations == []
assert result.analysis_error == "API key not set"
+ @pytest.mark.parametrize(
+ "error",
+ [
+ "`claude -p` failed (exit 1):\nPrompt is too long",
+ # What codex exec printed on a real learn run: it refuses a prompt over 2**20 chars.
+ "`codex exec` failed (exit 1):\nError: turn/start: turn/start failed: Input exceeds "
+ "the maximum length of 1048576 characters. (code -32602), data: "
+ '{"input_error_code":"input_too_large","max_chars":1048576,"actual_chars":1786526}',
+ ],
+ ids=["claude", "codex"],
+ )
@patch("headroom.learn.analyzer._call_llm")
- def test_retries_smaller_digest_on_prompt_too_long(self, mock_call_llm: MagicMock):
+ def test_retries_smaller_digest_on_prompt_too_long(self, mock_call_llm: MagicMock, error):
"""A context-overflow error rebuilds the digest at half the budget and retries."""
mock_call_llm.side_effect = [
- RuntimeError("`claude -p` failed (exit 1):\nPrompt is too long"),
+ RuntimeError(error),
{"context_file_rules": [], "memory_file_rules": []},
]
diff --git a/tests/test_learn/test_loop_weighting.py b/tests/test_learn/test_loop_weighting.py
index 3640c8208..85fab596d 100644
--- a/tests/test_learn/test_loop_weighting.py
+++ b/tests/test_learn/test_loop_weighting.py
@@ -26,6 +26,7 @@ from headroom.learn.fixtures import (
)
from headroom.learn.loops import (
_IDENTITY_FIELDS,
+ LoopPattern,
_canonical_signature,
_identity_input,
_signature_tokens,
@@ -37,6 +38,7 @@ from headroom.learn.models import (
Recommendation,
RecommendationTarget,
SessionData,
+ SessionEvent,
ToolCall,
)
@@ -150,6 +152,119 @@ class TestDigestSurfacesLoops:
digest = _build_digest(_project(), [one_off_error_session()])
assert "Detected Loops" not in digest
+ @pytest.mark.parametrize("max_tokens", [80_000, 10_000])
+ @pytest.mark.parametrize(
+ ("tool", "sample"),
+ [
+ ("Bash", "x" * 120),
+ ("Grep", "x" * 2000), # a long search pattern
+ ("Glob", "src/" * 500 + "*.py"), # a long path
+ ],
+ ids=["bash", "long-grep-pattern", "long-glob-path"],
+ )
+ def test_loop_section_stays_inside_the_digest_budget(self, tool, sample, max_tokens):
+ # Rendered whole, thousands of loops with hundreds of indices each made
+ # a 1.79M-char prompt, over Codex's 1,048,576-char input cap.
+ loops = [
+ LoopPattern(tool, "s", sample, 300, False, 1_000_000 - i, list(range(300)))
+ for i in range(2000)
+ ]
+ digest = _build_digest(_project(), [], loops=loops, max_tokens=max_tokens)
+ section = digest[digest.index("=== Detected Loops") :]
+ assert len(section) <= max_tokens # a quarter of the budget's chars
+ # The costliest loops are the ones kept, and the caller's list is intact.
+ assert "~1,000,000 tokens wasted" in section
+ assert "~999,000 tokens wasted" not in section
+ assert loops[0].sample_input == sample
+ assert len(loops[0].msg_indices) == 300
+
+ @pytest.mark.parametrize("max_tokens", [80_000, 10_000])
+ def test_loops_fit_beside_a_large_prior_patterns_section(self, tmp_path, max_tokens):
+ # The event stream cannot trim sections placed ahead of it, so the
+ # loops give way to the prior patterns, which are never cut.
+ bullets = "".join(f"- rule {i:06d} {'y' * 80}\n" for i in range(max_tokens * 4 // 100))
+ claude_md = tmp_path / "CLAUDE.md"
+ claude_md.write_text(
+ f"<!-- headroom:learn:start -->\n{bullets}<!-- headroom:learn:end -->\n"
+ )
+ project = ProjectInfo(
+ name="proj",
+ project_path=tmp_path,
+ data_path=tmp_path / "data",
+ context_file=claude_md,
+ )
+ loops = [
+ LoopPattern("Grep", "s", "x" * 2000, 300, False, 1_000_000 - i, list(range(300)))
+ for i in range(25)
+ ]
+ digest = _build_digest(project, [], loops=loops, max_tokens=max_tokens)
+ assert bullets.splitlines()[-1] in digest
+ assert "~1,000,000 tokens wasted" in digest
+ assert len(digest) <= max_tokens * 4
+
+ @pytest.mark.parametrize("with_loops", [False, True], ids=["no-loops", "loops"])
+ @pytest.mark.parametrize("with_events", [False, True], ids=["tool-calls", "events"])
+ @pytest.mark.parametrize("max_tokens", [80_000, 10_000])
+ def test_whole_digest_stays_inside_the_budget(self, max_tokens, with_events, with_loops):
+ # Far more session text than the budget: every line and its newline
+ # counts, and none goes in that would leave no room for the markers.
+ sessions = []
+ for s in range(5):
+ calls = [
+ ToolCall(
+ name="Bash",
+ tool_call_id=f"{s}-{i}",
+ input_data={"command": f"run {i}"},
+ output="e" * 300,
+ is_error=True,
+ msg_index=i,
+ )
+ for i in range(3000)
+ ]
+ events = (
+ [SessionEvent(type="tool_call", msg_index=c.msg_index, tool_call=c) for c in calls]
+ if with_events
+ else []
+ )
+ sessions.append(SessionData(session_id=f"s{s}", tool_calls=calls, events=events))
+ loops = (
+ [
+ LoopPattern("Grep", "s", "x" * 2000, 300, False, 1_000_000 - i, list(range(300)))
+ for i in range(2000)
+ ]
+ if with_loops
+ else []
+ )
+ digest = _build_digest(_project(), sessions, loops=loops, max_tokens=max_tokens)
+ assert len(digest) <= max_tokens * 4
+ assert "remaining" in digest and "sessions truncated" in digest
+
+ @pytest.mark.parametrize("with_events", [False, True], ids=["tool-calls", "events"])
+ @pytest.mark.parametrize("max_tokens", [80_000, 10_000])
+ def test_many_tiny_sessions_stay_inside_the_budget(self, max_tokens, with_events):
+ # Thousands of kept sessions, each closed by a blank line whose newline
+ # counts too; the marker reserve alone would absorb only ~100 of them.
+ sessions = []
+ for s in range(20_000):
+ call = ToolCall(
+ name="Bash",
+ tool_call_id=str(s),
+ input_data={"command": "ls"},
+ output="ok",
+ is_error=False,
+ msg_index=0,
+ )
+ events = [SessionEvent(type="tool_call", msg_index=0, tool_call=call)]
+ sessions.append(
+ SessionData(
+ session_id=f"s{s}", tool_calls=[call], events=events if with_events else []
+ )
+ )
+ digest = _build_digest(_project(), sessions, loops=[], max_tokens=max_tokens)
+ assert len(digest) <= max_tokens * 4
+ assert digest.count("=== Session ") > 500
+ assert "sessions truncated" in digest
+
# =============================================================================
# apply_loop_weighting