Commit Graph
2 Commits
Author SHA1 Message Date
Tejas ChopraandClaude Opus 5 a2bf5ed1ba fix(cache): stop prefix transforms from busting the provider cache (#3735)
## Why

A `cache_control` marker means the provider has already hashed
everything up to and including that point, and is billing it at the
**cache-read rate (0.1x)**. Rewriting any of those bytes busts the entry
and re-bills the whole prefix at the **write rate (1.25x)** — a 12.5x
swing that dwarfs anything the transform saves.

Preserving the `cache_control` *field* does **not** preserve the
*entry*. The provider keys on content, not on the marker. A transform
that copies the marker onto rewritten text reads as cache-safe and is
not.

The arithmetic: if a transform invalidates the prefix, it has to cut
**>92%** of tokens just to break even against leaving the cache intact.
Real compaction cuts single-digit percentages. It is never worth it.

## What was wrong

**`compact_tool_descriptions`** truncated tool descriptions with no
marker check at all. A client that pinned any tool lost its entire tools
prefix — and every message behind it — to save a few hundred bytes.

**`_compact_system_blocks`** rewrote pinned system text and copied the
marker onto the new block. Its own docstring said "`cache_control` and
other non-text fields are preserved unchanged", which is true of the
field and misleading about the effect.

## What changed

- Tool-description compaction is skipped when any tool carries a marker.
This mirrors guards that already exist on
`_sort_tools_deterministically` and on `any_tool_has_cache_control` in
the Rust live zone — this path was simply missed.
- System compaction now compacts only blocks **after** the last
breakpoint, via a new `_last_cache_control_index` helper.

Both transforms behave exactly as before when the client pins nothing —
the common case, and the one they were written for. Neither is silent:
the skip logs `event=tool_desc_compaction_skipped`.

## Tests

New `tests/test_cache_prefix_safety.py` (7 tests) covers both
transforms: pinned content stays byte-identical, unpinned content still
compacts, and a marker on the final block is a full no-op.

Two existing expectations changed, deliberately:

- `test_preserves_cache_control` asserted that a pinned block is
compacted *and* keeps its marker — precisely the bug. Replaced by
`test_marked_block_is_left_byte_identical`, plus a new test that
compaction still runs after the breakpoint.
- `_make_anthropic_payload_with_long_system` had a single pinned block,
so the guard made it a no-op. It now carries a pinned block followed by
dynamic content — the shape agentic clients actually send — so the tests
still exercise compaction while asserting the pinned block survives.

318 related tests pass; `ruff check` and `ruff format --check` clean.

## Scope

Not addressed here, tracked separately:

- Savings accounting clamps every component at `max(…, 0)`
(`savings_tracker.py:958-965`) and never debits `cache_bust_tokens_lost`
from the headline, so a net-negative deployment reports a gain.
`cost.py:496` already computes the honest figure and nothing consumes
it.
- `normalize_message_cache_control` was investigated and left alone: the
client-mirroring path is correct, and the legacy fallback deliberately
consolidates accumulated replay leftovers (#2375). An earlier attempt to
"preserve" markers there broke five existing tests for good reasons.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---

### Known limitation — read before relying on this

Adversarial review after the fact found the guard is **narrower than
this description implies**. It is not a regression, but it does not
fully deliver what the title promises, and that is worth recording
rather than discovering later.

Anthropic evaluates the cache prefix in the order **tools → system →
messages**, so a marker in a *later* section freezes every *earlier*
one. Neither new guard accounts for that:

1. **`compact_tools` is unguarded** (`tool_schema_compaction.py`,
`compact_tools`). It strips `$schema`/`title`/`examples` and collapses
whitespace on every `input_schema`, and it runs **first, on the same
array**, one block above the guard that was added. Verified on this
branch: a tools array containing a `cache_control`-marked tool is still
rewritten, 436 → 374 bytes. A client that pins its tools still gets its
whole tools prefix rewritten.
2. **A marker in `system` or `messages` does not stop tool compaction**,
even though tools sit inside that prefix. The updated test in this PR
encodes exactly this: it pins `system[0]`, then asserts the tools were
compacted anyway — so the cached prefix is busted on the very request
where the new system guard carefully preserved `system[0]`
byte-for-byte.
3. **`_compact_system_blocks` ignores markers in `messages`.** A client
whose only breakpoint sits on the last user message has its whole system
array inside the cached prefix, yet `frozen_upto == -1` and every block
is rewritten. Fixing this needs a signature change — the function only
receives `blocks`, not the payload.

Net: this helps a client that pins **only** system, and buys little for
one that pins its tools. Fixing it properly requires cross-section
marker awareness, and the tools-side guard must be widened *after* (2)
is fixed, not before — widening it first makes things worse.

Merging as incremental progress with the limitation stated. Follow-up
tracked separately.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-23 22:39:33 +02:00
3dd9660d91 feat: 3-layer context compression pipeline (L1+L2+L3) (#1405)
## Description

> **Default behavior is unchanged:** only L1 (annotation-key stripping)
is on by default. L2 (description truncation) and L3 (system-prompt
compression) are **opt-in** via `HEADROOM_TOOL_DESC_MAX_CHARS` and
`HEADROOM_SYSTEM_COMPACT=1` respectively — instruction-level compression
never runs unless an operator explicitly enables it. Verified in
`system_compact.py`: `system_compact_enabled()` returns `False` when the
env var is unset.

Reduces MCP-injected context overhead (~40K tokens / 20% of a 200K
window) through a progressive 3-layer compression pipeline. Each layer
is independently controlled, fail-safe, and additive — operators can
enable L1 only (default) or opt into L2/L3 for deeper savings.

### Layer 1: Tool Schema Annotation Key Stripping (default on)
- Strip JSON Schema annotation keys (`$schema`, `title`, `examples`,
`deprecated`, `default`, `readOnly`, `writeOnly`) from tool definitions
- Normalise whitespace in `description` fields
- Zero risk — removes only non-constraint metadata that models ignore
- ~8% savings on tool schema size

### Layer 2: Tool Description Truncation (opt-in:
`HEADROOM_TOOL_DESC_MAX_CHARS`)
- Truncate verbose tool/parameter descriptions to configurable length
- Preserves first complete sentence (critical for model tool selection)
- Optionally appends second sentence within 1.5× budget
- Hard-truncates with `...` if a single sentence exceeds limit
- Recursively processes nested `description` fields in
`input_schema`/`parameters`
- ~43% savings on description text (estimated ~17K tokens)

### Layer 3: System Prompt CCR Compression (opt-in:
`HEADROOM_SYSTEM_COMPACT`)
- Compress `system[]` content blocks using existing
`ContentRouter.compress()`
- Only compresses blocks exceeding `HEADROOM_SYSTEM_COMPACT_MIN_CHARS`
(default 500)
- Preserves `cache_control` markers and non-text blocks
- Fail-safe: leaves block unchanged if compression fails or doesn't save
size
- ~14.5% savings on system prompt (estimated ~3.5K tokens)

**Combined savings (all 3 layers enabled): ~40K → ~17K tokens (~58%
reduction)**

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/tool_schema_compaction.py` — New shared module: L1
annotation stripping + L2 description truncation with
`strip_annotation_keys()` and `truncate_descriptions()`
- `headroom/proxy/system_compaction.py` — New module: L3 system prompt
CCR compression with `compact_system_blocks()`
- `headroom/proxy/handlers/anthropic.py` — Add L1+L2+L3 call sites
(after tool assembly, before PRE_SEND)
- `headroom/proxy/handlers/openai.py` — Add L1+L2+L3 call sites
(parallel to Anthropic handler)
- `tests/test_tool_schema_compaction.py` — 42 unit tests covering edge
cases, nested schemas, fail-safe behavior
- `tests/test_system_compaction.py` — Tests for L3 compression,
cache_control preservation, min-chars gating

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ uv run pytest tests/test_tool_schema_compaction.py tests/test_system_compaction.py tests/test_anthropic_compaction_transforms.py -v
===== 49 passed in 4.96s =====

$ uv run ruff check <changed files>
All checks passed!

$ uv run mypy headroom/proxy/tool_schema_compaction.py headroom/proxy/system_compaction.py headroom/proxy/handlers/anthropic.py headroom/proxy/handlers/openai.py
Success: no issues found in 4 source files

# Manual verification with HEADROOM_TOOL_DESC_MAX_CHARS=120
# Single tool schema: 548→434 bytes (L1, 20.8% saved) → 315 bytes (L2, 27.4% saved)
# Combined: 548→315, 42.5% saved
# Full request with proxy: orig=39179 opt=31988 saved=7191 (18.4% compression)
```

## Real Behavior Proof

- Environment: macOS, Python 3.13, headroom proxy v0.28.0, Claude Code
CLI
- Exact command / steps:
1. Start proxy with `HEADROOM_TOOL_DESC_MAX_CHARS=120
HEADROOM_SYSTEM_COMPACT=1 headroom proxy`
  2. Route Claude Code traffic through proxy
  3. Check `/stats` endpoint for `transforms_applied` and byte savings
- Observed result: L1/L2/L3 transforms applied correctly, ~58% token
reduction on MCP-heavy context
- Not tested: Windows, production deployment

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A

## Additional Notes

- L2 and L3 are **opt-in** via env vars. Default behavior is unchanged
(only L1 active).
- All layers have fail-safe fallbacks — if compaction fails or doesn't
reduce size, the original payload passes through unchanged.
- The Anthropic handler now appends `anthropic:tool_schema_compaction`
(L1), `anthropic:tool_desc_compaction` (L2), and
`anthropic:system_compact` (L3) to `transforms_applied`, so `/stats` and
transformation accounting are no longer blind to compression that
changed the request. Covered by handler-level e2e regression in
`tests/test_anthropic_compaction_transforms.py` (positive + negative
cases). The earlier follow-up #1423 is superseded — no longer needed.

---------

Signed-off-by: lg320531124 <lg320531124@users.noreply.github.com>
Co-authored-by: lg320531124 <lg320531124@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-07-15 19:58:51 +00:00