akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/REALIGNMENT/09-phase-G-rtk-observability.md
Tejas Chopra e0ce4b1d48
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

203 lines
9.7 KiB
Markdown
Raw Permalink 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:
1. Ensures the RTK binary is installed (`_ensure_rtk_binary()`).
2. Injects the `<!-- headroom:rtk-instructions -->` block into the agent's instruction file (AGENTS.md / .cursorrules / etc.).
3. Spawns the proxy (or attaches to a running one).
4. 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.**
Reference in a new issue View git blame Copy permalink