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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(learn): keep the digest's loop section inside its budget (#4269)
gglucass506ba16c4a7f
diff --git a/headroom/learn/analyzer.py b/headroom/learn/analyzer.pyindex 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 toolong"), 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 = Falsefor 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)"+ )+ breaklines.append(session_header)- chars_used += len(session_header)+ chars_used += len(session_header) + 1# Use events if available (richer context), fall back to tool_callsif 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 = Truebreak- 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) + 1else: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 = Truebreak- tc_line = _format_tool_call(tc)lines.append(tc_line)- chars_used += len(tc_line)+ chars_used += len(tc_line) + 1lines.append("")+ chars_used += 1return "\n".join(lines)diff --git a/headroom/learn/loops.py b/headroom/learn/loops.pyindex 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+@dataclassclass 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.pyindex 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.pyindex 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