mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00

fix: remove rtk and lean-ctx CLI context tools (#2677 )

## Description

Removes both third-party CLI context tools — **rtk** and **lean-ctx** —
and with them the context-tool selector itself. Headroom no longer
downloads, installs or configures either one, and there is no
replacement.

The previous pass (#2344) gated only three entry points inside
`headroom/cli/wrap.py`. That left the feature reachable in practice:

| Gap | Effect |
|---|---|
| `scripts/install.sh:1544`, `install.ps1:1681` | Ran `rtk init --global
--auto-patch` from bash/PowerShell, **bypassing the Python gate
entirely** — `curl \| sh` still wrote a Claude Code `PreToolUse` hook
regardless of `HEADROOM_RTK` |
| `wrap.py` `_setup_context_tool_for_agent` | **`wrap openhands` was
broken by default**: `rtk_required=True` met a gate returning `None` →
`SystemExit(1)`. Invisible because all 8 openhands tests patched
`_ensure_rtk_binary` to a fake path |
| `proxy/helpers.py`, `subscription/tracker.py` | Proxy shelled out to
`rtk gain` from `/stats`, the dashboard and `headroom perf`; the tracker
polled it per contribution (`_RTK_WIRING_DEFAULT = "enabled"`) |
| No cleanup path | Nothing removed artifacts an earlier default had
installed, so a machine that once ran the old default kept rtk in the
loop forever (#1669, #1955) |

Also worth noting: the rtk binary download had **no SHA or signature
verification** — only `rtk --version` as a smoke test.

## Type of Change

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

## Changes Made

**Removed** — `headroom/rtk/` and `headroom/lean_ctx/` packages,
`headroom/cli/wrap_rtk_metrics.py`, `_selected_context_tool` /
`_setup_context_tool_for_agent` / `_VALID_CONTEXT_TOOLS`, the `--rtk` /
`--no-rtk` / `--no-project-rtk` / `--keep-rtk` flags across all 18 wrap
subcommands, `HEADROOM_RTK*`, the proxy-side `rtk gain` polling, the
dashboard CLI-filtering panel (rows + all 8 `cliFiltering*` Alpine
getters), `paths.rtk_path()` / `lean_ctx_path()`, the SDK path helpers,
`benchmarks/rtk_loop_learn_eval.py`, and the `headroom/rtk/**` CI path
filters.

**Fails loudly, not silently** — `--context-tool` / `--no-context-tool`
/ `HEADROOM_CONTEXT_TOOL` are kept solely to error out. They live in
shell profiles, aliases and CI jobs, and accepting them as a no-op would
read as Headroom having quietly stopped working. The installers reject
them too, which matters more than it looks: their arg parsers forward
the first unknown flag **and everything after it** to the wrapped tool,
so a leftover `--no-rtk` would have silently swallowed a following
`--port` and then been ignored downstream.

**New `headroom/context_tool_cleanup.py`** — deleting the code cannot
help a machine that already ran the old default, since the hooks,
binaries and injected guidance are durable on disk.
`purge_context_tool_artifacts()` runs once per `wrap`/`unwrap` and
removes the registered hook entries, the generated hook scripts, the
Headroom-managed `~/.local/bin` symlinks, the vendored
`~/.headroom/bin/{rtk,lean-ctx}` binaries, the `lean-ctx` MCP server
entry and the marker-fenced instruction blocks. Deliberately
conservative: idempotent, **skips** a malformed config rather than
overwriting it, and only unlinks a symlink resolving inside Headroom's
own bin dir so a user's own build is untouched. It reports on
**stderr**, because `wrap/unwrap openclaw --prepare-only` emit
machine-readable JSON on stdout as their entire contract. Skipped for
`wrap selfheal` (runs from a SessionStart hook; must not race Claude
Code's writer for `~/.claude.json`) and for `--help`, which must stay
read-only.

**Client-config hardening** (discovered while investigating a "corrupted
Serena settings file" report) — `wrap.py` reset a settings file to `{}`
when an existing file would not parse, then wrote that back. One
hand-edited typo or a transient `EACCES`/`EINTR` on a valid file
destroyed the user's `permissions`, `env` and `hooks`, on **every
`headroom wrap claude`**. It now refuses to write. Separately,
`fsutil.write_text` is now atomic (temp file + `fsync` + `os.replace`),
fixing all 14 non-atomic client-config writes at once; it follows
symlinks rather than replacing them (dotfile managers) and preserves an
existing file's mode.

**Deliberately kept** — `rtk` stays in the wrapper-peel list in
`transforms/content_router.py`. It sits beside `sudo`/`env`/`timeout` as
shell-command grammar, so `rtk cat f` is still classified as a file read
for anyone running their own rtk install, which the purge intentionally
leaves alone.

## 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
$ ruff check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates
All checks passed!

$ ruff format --check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates
1255 files already formatted

$ mypy headroom/
Success: no issues found in 508 source files

$ pytest tests/test_context_tool_cleanup.py -q
11 passed

$ pytest tests/test_fsutil.py -q
12 passed

$ pytest tests/test_cli/test_wrap_codex.py -q            # 89 tests
89 passed in 431.68s
$ pytest tests/test_cli/test_wrap_opencode.py -q
39 passed in 257.46s
$ pytest tests/test_cli/test_wrap_helpers.py -q
45 passed
$ pytest tests/test_paths.py -q
75 passed
$ pytest tests/test_cli/test_unwrap_claude.py -q
14 passed
$ pytest tests/test_proxy_savings_history.py -q
39 passed
$ pytest tests/test_cli/test_wrap_copilot.py -q
27 passed
$ pytest tests/test_cli/test_wrap_zcode.py -q
20 passed
$ pytest tests/test_subscription_tracker.py -q
9 passed
$ pytest tests/test_proxy_dashboard_stats_cache.py -q
5 passed, 1 skipped
```

Repo-wide grep for 14 removed symbols (`headroom.rtk`,
`headroom.lean_ctx`, `_ensure_rtk_binary`, `_selected_context_tool`,
`_get_context_tool_stats`, `rtk_path`, `lean_ctx_path`,
`wrap_rtk_metrics`, `HEADROOM_RTK`, `cli_tokens_avoided`,
`tokens_saved_rtk`, …) across `*.py`, `*.ts`, `*.sh`, `*.ps1`, `*.yml`,
`*.html`: **zero hits**.

Notable test changes: `test_wrap_openhands.py` no longer patches
`_ensure_rtk_binary` and asserts `wrap openhands --prepare-only` exits 0
unpatched — the regression that was previously masked.
`test_wrap_continue.py` and `test_wrap_hintfile_agents.py` were removed
(every test drove RTK instruction injection). A new
`test_subscription_tracker.py::test_load_state_written_before_cli_context_tools_were_removed`
proves a pre-removal `subscription_state.json` still loads.

## Real Behavior Proof

- **Environment:** macOS 15.4 (darwin 25.4.0), Python 3.12.6, Headroom @
this branch, real `~/.headroom` and `~/.claude` on the dev machine.
- **Exact command / steps and observed result:**

```text
# 1. Retired flag fails loudly instead of silently no-op'ing
$ headroom wrap codex --prepare-only --context-tool rtk
Error: CLI context tools (rtk, lean-ctx) have been removed from Headroom: they
rewrote shell commands through a third-party binary Headroom no longer manages.
Drop --context-tool / --no-context-tool and unset HEADROOM_CONTEXT_TOOL;
`headroom wrap` uninstalls what they left behind on first run.

$ HEADROOM_CONTEXT_TOOL=lean-ctx headroom wrap codex --prepare-only
Error: CLI context tools (rtk, lean-ctx) have been removed from Headroom: ...

# 2. install.sh rejects the retired flags (extracted parse_wrap_args harness)
['--no-rtk', '--port', '9999']   rc=1  ERROR: CLI context tools ... Drop --no-rtk
['--context-tool=rtk']           rc=1  ERROR: CLI context tools ... Drop --context-tool
$ bash -n scripts/install.sh   # syntax OK

# 3. Purge ran against the real machine, which had all the orphaned artifacts
$ python -c "from headroom.context_tool_cleanup import purge_context_tool_artifacts; ..."
  removed ~/.headroom/bin/lean-ctx        (51 MB)
  removed ~/.headroom/bin/rtk             (7.7 MB)
  removed ~/.local/bin/rtk                (symlink into ~/.headroom/bin)
  removed ~/.claude/hooks/rtk-rewrite.sh
  removed 8 lean-ctx-* hook scripts
# ~/.claude.json afterwards: 90 top-level keys, 19 projects, mcpServers unchanged
# → ~59 MB reclaimed, no unrelated key touched

# 4. stdout stays machine-readable while the purge reports (planted a fake artifact)
$ headroom wrap openclaw --prepare-only --gateway-provider-id codex >out 2>err
$ cat out
{"enabled":true,"config":{"proxyPort":8787,...}}     # parses as JSON
$ cat err
Retired CLI context tool cleanup: removed /Users/tcms/.headroom/bin/rtk

# 5. --help is inert (planted artifact survives), a real run purges
$ headroom wrap codex --help   → artifact survived: CORRECT
$ headroom wrap openclaw --prepare-only → purged: CORRECT

# 6. MCP purge dry-run against a copy of the real 82 KB ~/.claude.json
top-level keys 90 -> 90;  projects 19 -> 19;  LOST keys: none
all content outside mcpServers byte-identical: True
```

Dashboard rendered via the Playwright test after the panel removal:
"Token Savings" shows only `Proxy 0 (0.0%)` / `Of total wire: 36.86%`,
and "Token Usage" reads Before Compression → Proxy Removed → After
Compression with no "Filtered (this session)" row. Nothing below the
removed panel broke.

- **Not tested:** Windows and Linux (macOS only) — `install.ps1` is
verified by brace-balance and inspection, not executed, since no `pwsh`
is available locally. The wrap e2e suite (`e2e/wrap/run.py`) was updated
but not run; it needs the Docker e2e image. `serena project index`
interaction is exercised in the stacked base PR.

## 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
- [x] 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
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

**Stacked on #2676** (`tejas/serena-config-bootstrap`) — please merge
that first; this PR's base should then be retargeted to `main`, or it
will read as containing that fix too.

**Breaking-change migration for users:**
- Drop `--rtk`, `--no-rtk`, `--no-project-rtk`, `--keep-rtk`,
`--context-tool`, `--no-context-tool` from any alias, script or CI job,
and unset `HEADROOM_RTK*` / `HEADROOM_CONTEXT_TOOL`. They now error
rather than being ignored, so the failure is immediate and
self-explaining.
- Previously-installed artifacts are purged automatically on the next
`wrap`/`unwrap`; no manual cleanup needed.
- `headroom perf --json` no longer carries a `cli_filtering` key, and
`/stats` no longer returns a `context_tool` section.

**Docs:** `docs/rtk-architecture.md` deleted; RTK/lean-ctx removed from
`README.md`,
`docs/content/docs/{configuration,opencode,grok-build,docker-install,filesystem-contract}.mdx`,
`docs/observability.md` and the matching `wiki/` pages.
`REALIGNMENT/09-phase-G-rtk-observability.md` is marked SUPERSEDED
rather than deleted, to keep the planning record.

**Follow-ups not in scope:** `_emit_wrap_interrupted` was deleted as
dead code — its only caller was the `except KeyboardInterrupt` guarding
the binary download, so with no download there is nothing slow left to
interrupt.

2026-07-30 22:59:41 -07:00

9.7 KiB

Raw Blame History

Phase G — RTK Breadth + Observability

SUPERSEDED. RTK and lean-ctx were removed from Headroom entirely: the headroom/rtk/ and headroom/lean_ctx/ packages, all --rtk / --context-tool flags, the wrap-side hooks and hint-file injection, and the proxy-side rtk gain polling are all gone, and headroom/context_tool_cleanup.py uninstalls what earlier versions left on disk. The RTK-specific plan below is historical; the non-RTK observability items (cache-hit rate, compression ratio, token validation) were kept. docs/rtk-architecture.md, referenced throughout this document, was deleted with the feature.

Goal: Extend RTK coverage to more wrap-CLI agents; close the dead tokens_saved_rtk data plane; add per-invocation RTK metrics; add the cache-hit-rate, compression-ratio, token-validation observability surface that's missing today.

Calendar: 1 week.

Shape: 3 PRs.

Decision context: Per Agent F audit and 2026-05-01 user direction, RTK stays on the wrap-CLI side, NOT the proxy side. Proxy-side invocation is rejected because (a) cache hot zone risk on tool_result content compression, (b) parallel implementation with crates/headroom-core/src/transforms/log_compressor.rs, (c) RTK rewrites commands not outputs — different value proposition. "Integrate RTK with everything" reads as "extend wrap-CLI breadth + close the data plane + observability."

PR-G1 — Wrap CLI breadth: cline, continue, goose, openhands

Branch: realign-G1-wrap-more-agents Worktree: ~/claude-projects/headroom-worktrees/realign-G1-wrap-more-agents Risk: LOW LOC: +800

Scope

Eliminate P5-62. Add headroom wrap cline, headroom wrap continue, headroom wrap goose, headroom wrap openhands (extending the existing pattern from wrap claude / wrap codex / wrap aider / wrap copilot / wrap cursor). Each wrap subcommand:

Ensures the RTK binary is installed (_ensure_rtk_binary()).
Injects the  block into the agent's instruction file (AGENTS.md / .cursorrules / etc.).
Spawns the proxy (or attaches to a running one).
Launches the agent CLI with proxy env-var overrides.

Files

Add:

headroom/cli/wrap/cline.py — wrap implementation for Cline (agent that lives in VS Code; instruction file is .clinerules).
headroom/cli/wrap/continue_dev.py — Continue agent (.continue/config.json configuration; system message injection).
headroom/cli/wrap/goose.py — Goose agent (Block's CLI; .goose/config.yaml).
headroom/cli/wrap/openhands.py — OpenHands (instruction injection via OPENHANDS_INSTRUCTIONS env var).

Modify:

headroom/cli/wrap/__init__.py — register new subcommands.
headroom/cli/main.py — headroom wrap --help lists new agents.
e2e/wrap/run.py — extend the e2e runner to exercise the new wrappers (each wrapper has a smoke test that asserts: binary installed, instruction injected, proxy started, dummy LLM call works).

Tests added:

tests/test_cli/test_wrap_cline.py::test_wrap_cline_smoke
tests/test_cli/test_wrap_continue.py::test_wrap_continue_smoke
tests/test_cli/test_wrap_goose.py::test_wrap_goose_smoke
tests/test_cli/test_wrap_openhands.py::test_wrap_openhands_smoke
tests/test_cli/test_wrap_idempotent_inject.py::test_double_injection_no_duplicate_block (for each new wrapper)

Acceptance criteria

Tests pass.
Manual test: headroom wrap cline -- claude-3-7-sonnet launches a Cline session with the proxy in-front and RTK instructions in .clinerules.

Blocked by

None.

Blocks

None.

Rollback

git revert. Existing wrappers continue working; new ones absent.

Notes

Future agents to add later (not in this PR): Roo Code, Devin-style CLIs, raw gh copilot standalone, gpt-engineer, sweep, smol-developer. Add as separate PRs as adoption justifies.

PR-G2 — Wire `tokens_saved_rtk` data plane

Branch: realign-G2-tokens-saved-rtk Worktree: ~/claude-projects/headroom-worktrees/realign-G2-tokens-saved-rtk Risk: LOW LOC: +200

Scope

Eliminate P5-60. The tokens_saved_rtk field on SubscriptionContribution (headroom/subscription/models.py:260) exists but is never populated. Wire it: poll rtk gain --format json periodically (already done by _get_rtk_stats in helpers.py:132), diff the cumulative tokens_saved since last snapshot, and feed into tracker.update_session_savings(tokens_saved_rtk=delta).

Files

Modify:

headroom/subscription/tracker.py — add _last_rtk_tokens_saved: int = 0 state; on every update_session_savings call, fetch _get_rtk_stats(), compute delta = current.tokens_saved - self._last_rtk_tokens_saved, set tokens_saved_rtk=delta, update state.
headroom/proxy/helpers.py:132 — _get_rtk_stats returns RtkStats { invocations: int, tokens_saved: int, last_run_at: datetime }. Memoization stays at 5s.

Tests added:

tests/test_subscription_tracker_rtk_wired.py::test_tokens_saved_rtk_populated_from_rtk_stats
tests/test_subscription_tracker_rtk_wired.py::test_delta_computed_correctly_across_polls
tests/test_subscription_tracker_rtk_wired.py::test_rtk_failure_zero_delta_no_throw

Acceptance criteria

Tests pass.
A wrap session with RTK invocations produces tokens_saved_rtk > 0 after the session ends.

Blocked by

None.

Blocks

None.

Rollback

git revert. tokens_saved_rtk returns to silent zero.

PR-G3 — Per-invocation RTK metrics + observability gaps

Branch: realign-G3-rtk-metrics-and-obs Worktree: ~/claude-projects/headroom-worktrees/realign-G3-rtk-metrics-and-obs Risk: LOW LOC: +600

Scope

Eliminate P6-68, P6-69, P5-58, P4-41, P4-42, P4-45, and P5-61 (documentation). Add Prometheus metrics:

wrap_rtk_invocations_total{tool} — derived from rtk gain --format json polling (tool label is the git, ls, cargo, etc. command).
wrap_rtk_tokens_saved_per_session — histogram, populated at session end.
proxy_cache_hit_rate_per_session — histogram, computed from usage.cache_read_input_tokens / total_input_tokens per session.
proxy_compression_ratio_by_strategy{strategy, content_type} — histogram.
proxy_compression_rejected_by_token_check_total{strategy} — counter (already in PR-B4; ensure it's exported here).
proxy_passthrough_bytes_modified_total{path} — gauge that must stay 0 outside compression-on path. Alarm if non-zero.
proxy_rate_limit_remaining_* — extracted from upstream response headers.
proxy_service_tier_count_total{tier} — counter for service_tier distribution.
proxy_response_status_count_total{status} — incomplete | failed | cancelled | completed | in_progress.
proxy_image_generation_call_log_redacted_total — counter for log redactions of multi-MB base64.

Plus image base64 log redaction (P4-45) lands here.

Files

Modify:

crates/headroom-proxy/src/observability/prometheus.rs — add all new metrics.
crates/headroom-proxy/src/sse/anthropic.rs — emit proxy_cache_hit_rate_per_session from usage.cache_read_input_tokens / total_input_tokens on message_delta.
crates/headroom-proxy/src/sse/openai_responses.rs — emit on response.completed.
crates/headroom-proxy/src/sse/openai_chat.rs — emit on final usage chunk.
crates/headroom-proxy/src/handlers/responses.rs — extract and log service_tier.
crates/headroom-proxy/src/handlers/responses.rs — log incomplete_details.reason when status == incomplete.
headroom/proxy/request_logger.py — redact base64 strings >1024 bytes; replace with <base64 truncated, X bytes>.
crates/headroom-proxy/src/observability/cache_hit_rate.rs — new module.
crates/headroom-proxy/src/observability/compression_ratio.rs — new module.

Add:

docs/observability.md — documents every metric, what it means, what an operator should do when it drifts.
docs/rtk-architecture.md — explicitly documents the decision: RTK is wrap-CLI-only; proxy-side invocation is rejected. Includes the rationale (cache hot zone, parallel-impl with log_compressor, command-rewrite-vs-output-rewrite). Future contributors hit this doc before considering a proxy-side RTK call.

Tests added:

crates/headroom-proxy/tests/integration_metrics.rs::cache_hit_rate_emitted_per_session
crates/headroom-proxy/tests/integration_metrics.rs::compression_ratio_emitted_per_strategy
crates/headroom-proxy/tests/integration_metrics.rs::passthrough_bytes_modified_zero_when_no_compression
crates/headroom-proxy/tests/integration_metrics.rs::service_tier_logged
crates/headroom-proxy/tests/integration_metrics.rs::incomplete_status_logged_with_reason
tests/test_image_log_redaction.py::test_large_base64_truncated

Acceptance criteria

All tests pass.
Manual scrape of /metrics shows the new metric families.
docs/rtk-architecture.md reviewed and approved.

Blocked by

None.

Blocks

None.

Rollback

git revert. Loses observability; no functional regression.

Phase G acceptance summary

After all 3 PRs land:

✅ Wrap CLI coverage extends to cline, continue, goose, openhands
✅ tokens_saved_rtk field populated end-to-end
✅ Per-invocation RTK Prometheus metrics
✅ Per-session cache-hit-rate metric
✅ Per-block compression-ratio histogram
✅ Token-validation rejection counter
✅ Passthrough-bytes-modified gauge (alarm-able)
✅ Rate-limit headers observed and exported
✅ service_tier distribution metric
✅ Response status (incomplete | failed | cancelled) logged with reason
✅ Image base64 log redaction
✅ docs/rtk-architecture.md documents the keep-RTK-on-wrap-side decision

Phase G retires P4-41, P4-42, P4-45, P5-58, P5-60, P5-61, P5-62, P6-68, P6-69, P6-72.

9.7 KiB Raw Blame History

Phase G — RTK Breadth + Observability

PR-G1 — Wrap CLI breadth: cline, continue, goose, openhands

Scope

Files

Acceptance criteria

Blocked by

Blocks

Rollback

Notes

PR-G2 — Wire tokens_saved_rtk data plane

Scope

Files

Acceptance criteria

Blocked by

Blocks

Rollback

PR-G3 — Per-invocation RTK metrics + observability gaps

Scope

Files

Acceptance criteria

Blocked by

Blocks

Rollback

Phase G acceptance summary

9.7 KiB

Raw Blame History

PR-G2 — Wire `tokens_saved_rtk` data plane