fix(kompress): accept ccr_original on the remote compressor

[chopratejas]

Description

From a user's proxy log (Copilot Chat 0.61.0 on Windows, VS Code 1.133.0, Headroom 0.36.x). This appears on every single request:

WARNING Kompress failed: RemoteKompressCompressor.compress() got an
        unexpected keyword argument 'ccr_original'
INFO    [router] route_counts={'ratio_too_high': 1, 'cache_miss': 1} compressed=0 frozen=1 msgs=2
INFO    Transform content_router: 1611 -> 1611 tokens (saved 0) [48.3ms]
INFO    PERF model=... tok_before=1623 tok_after=1623 tok_saved=0 tool_saved=0 savings=none

RemoteKompressCompressor's module docstring promises the class "mirrors KompressCompressor's public surface (is_ready / preload / ensure_background_load / compress), so it is a drop-in at the ContentRouter seam". That promise lapsed — the local compress gained a ccr_original keyword and the remote one did not.

ContentRouter._try_ml_compressor passes ccr_original whenever custom tags are protected. The comment there reads:

Only set it when tags were protected so callers/compressors that don't accept the kwarg are unaffected on the common path.

That assumption is wrong. The remote compressor is affected: the call raises TypeError, which the surrounding broad except Exception catches and downgrades to logger.warning("Kompress failed: %s", e). The request then forwards uncompressed and the proxy reports success.

The blast radius is the entire deployment, not one request. _get_kompress returns the remote compressor ahead of every local path, so on any install with HEADROOM_KOMPRESS_ENDPOINT set — precisely the sandboxed/enterprise deployment this class exists to serve — ML compression was silently disabled while every dashboard read "working, 0 tokens saved".

Closes #

Type of Change

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

Changes Made

Two parts, because fixing only the crash would leave the bug ccr_original exists to prevent:

• Accept the keyword on RemoteKompressCompressor.compress, so the seam contract actually holds.
• Honor it — store the pre-protection text in CCR rather than the placeholder intermediate, so a later full retrieval returns the real block instead of {{HEADROOM_TAG_N}}. The endpoint's own original_tokens describes content, so when an override is supplied the stored text is counted locally; the common path (no override) keeps the endpoint's count exactly as before.
• A signature-compatibility test over the two compress methods, so this drift cannot recur silently. It compares public keywords only — _deadline_started_at is underscore-prefixed and only ever passed by kompress_compressor to itself on its recursive batch path, never across the seam.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

$ pytest tests/test_remote_kompress_dropin.py -q
8 passed in 0.25s

# Same file against pre-fix code (git stash) — reproduces the reported error:
3 failed, 5 passed
  FAILED test_remote_compress_accepts_every_local_keyword
  FAILED test_passing_ccr_original_no_longer_raises
  FAILED test_ccr_stores_the_pre_protection_text_not_the_placeholder
  E  TypeError: RemoteKompressCompressor.compress() got an unexpected
     keyword argument 'ccr_original'

$ pytest tests/ -q -k "kompress or content_router"
411 passed, 9 skipped

$ pytest tests/ -q          # this branch
6 failed, 11381 passed, 587 skipped in 446.31s

All 6 also fail on clean origin/main, same machine — pre-existing, not regressions:
  test_graceful_shutdown.py::test_run_server_installs_cancelled_error_filter
  test_learn/test_integration.py::TestCodexIntegration::test_full_pipeline
  test_release_workflows.py::test_no_native_tls_in_wheel_build_tree
  test_providers/test_deepseek.py::...v4_flash_litellm_pricing
  test_providers/test_deepseek.py::...v4_pro_litellm_pricing
  test_providers/test_deepseek.py::...cost_per_token_resolves_deepseek_v4_flash
(verified by stashing this branch and running test_deepseek.py: 3 failed, 17 passed)

$ ruff check headroom/
All checks passed!

$ mypy headroom/transforms/kompress_remote.py
Success: no issues found in 1 source file

Real Behavior Proof

• Environment: macOS, Python 3.12.13, branch on origin/main @ a3821378.
• Exact command / steps: drove RemoteKompressCompressor.compress with the exact kwargs ContentRouter._try_ml_compressor builds when protected is truthy (context, question, target_ratio, allow_download, ccr_original), against a stubbed HTTP client.
• Observed result: pre-fix that call raises TypeError: ... unexpected keyword argument 'ccr_original' — byte-identical to the user's log line. Post-fix it returns a KompressResult, and CCR receives the pre-protection text ("HEADROOM_TAG" not in stored) with a token count matching what was stored.
• Not tested: no live remote Kompress endpoint was contacted; the HTTP client is stubbed. The end-to-end path through a running proxy against a real HEADROOM_KOMPRESS_ENDPOINT has not been exercised here.

Runtime Rollout Safety

• Rollout-managed feature(s): none. Affects deployments with HEADROOM_KOMPRESS_ENDPOINT set.
• Minimum rollout channel: n/a.
• Stable/default behavior changed: for remote-Kompress deployments, compression starts working again where it previously no-op'd. Deployments without the endpoint set are untouched — they never reach this class.
• Kill switch / disable path: unchanged (HEADROOM_KOMPRESS_ENDPOINT unset, or kompress_model="disabled").
• Unsafe override required: none.
• Qualification impact: the remote compressor's fail-open contract is unchanged — a bad endpoint still passes content through verbatim.
• Rollback path: revert; behavior returns to silently-disabled compression on remote deployments.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Fill in Real Behavior Proof → Environment.
• Fill in Real Behavior Proof → Exact command / steps.
• Fill in Real Behavior Proof → Observed result.
• Fill in Real Behavior Proof → Not tested.
• Fill in Runtime Rollout Safety → Rollout-managed feature(s).
• Fill in Runtime Rollout Safety → Minimum rollout channel.
• Fill in Runtime Rollout Safety → Stable/default behavior changed.
• Fill in Runtime Rollout Safety → Kill switch / disable path.
• Fill in Runtime Rollout Safety → Unsafe override required.
• Fill in Runtime Rollout Safety → Qualification impact.
• Fill in Runtime Rollout Safety → Rollback path.

Please update the PR body, or move the PR back to draft while it is still in progress.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!