feat(eco): /eco — RTK-style token compression for Bash tool output

[ericleepi314]

Summary

/eco — RTK-style token compression for Bash tool output, ported from the RTK deep-dive (my-docs/token-compression/RTK/, gitignored). When toggled on, the model-bound rendering of Bash results is compressed by deterministic filters — no model calls, no command rewriting — with every lossy transform backed by an on-disk recovery file. 60–90% fewer tokens on the outputs that dominate agent sessions (test runs, installs, long listings, log streams).

Usage: /eco (toggle) · /eco on|off · /eco status (session savings, per-filter breakdown). Session-scoped, same state shape as /effort ultracode; applies to subagent Bash calls in the same process.

Methods (from RTK)

Filter	What it does	Class
test_runner	pytest / cargo test / go test / jest native output → all-green runs collapse to one line; failures kept verbatim (relevant-line selection, cap 10)	tee-backed
noise-strip	command-family-scoped ceremony removal: git advice/progress lines, pip/npm/cargo/docker/apt/brew download+progress chatter	safe-loss (pure ceremony)
log-dedup	≥80-line loggy outputs → [×N]-counted unique errors/warnings over normalized lines (ts/uuid/hex/num/path)	tee-backed
head-cap	>400-line success outputs → first 60 lines + runnable [see remaining: tail -n +61 …]	tee-backed

Safety invariants (critic-reviewed, tested):

• never_worse guard: compressed rendering is compared against the exact baseline the mapper would emit; baseline wins → passthrough. Worst case = 0% savings.
• No unrecoverable loss: capping/summarizing filters must tee the full raw output to the per-session dir (next to the Step-11 tool-results/) and append a [full output: …]/tail -n +N hint, or the hit is discarded. Tee filenames are collision-proof (time_ns+pid+counter).
• Exit codes, is_error, interrupted/timeout/background/image/cd paths: untouched. A green test summary with a non-zero exit is treated as untrusted (→ passthrough), never masked behind an all-green one-liner.
• Any filter/engine exception → passthrough. 10 MiB input cap (Step-11 <persisted-output> already covers giants).
• Mapper assembly is byte-identical when eco is off/absent (all stdout/stderr/interrupted combinations covered by tests).

Note: the TUI transcript renders the mapped content, so with eco on the user sees the same compact rendering the model does; raw stdout/stderr stay in the output dict and the tee files.

Wiring

• src/eco/{state,guard,tee,filters,engine}.py — pure, no tool_system imports.
• bash_tool.py: _maybe_apply_eco on the success path (full pre-truncation output) → output["ecoContent"]; _bash_map_result_to_api honors it; _assemble_bash_body factored so the guard's baseline is exactly the wire assembly.
• /eco LocalCommand (headless-safe) + agent-server eco control + TUI SLASHES entry + dispatch case.

Evaluation (live command corpus through the real engine)

command                    exit  base tok  eco tok filter       result
pytest verbose all-pass       0      1059       47 pytest       -96%
pytest with failure           1       308       79 pytest       -74%
git status                    0       175      125 noise-strip  -29%
find src -type f              0     13093      635 head-cap     -95%
seq 1 2000                    0      2223       84 head-cap     -96%
repetitive log                0      6250      114 log-dedup    -98%
git log -50 / small outputs        (correctly passed through untouched)
TOTAL                               24241     2217              -91%

Testing

• 53 new tests (tests/test_eco.py, tests/test_bash_eco_integration.py): per-filter fixtures with ≥60% savings floors, never-worse property, tee collision/rotation/UTF-8-boundary, orphan-file avoidance, exit-code cross-checks, git state-line preservation, end-to-end _bash_call+mapper with eco on/off.
• Full repo suite green.
• Protocol e2e: real agent-server --stdio driven over NDJSON — eco on/status/off/bad-arg all correct.
• Live TUI e2e (pyte): real Ink TUI + real backend — /eco in slash menu, toggles on, status reports, toggles off.
• Design + implementation reviewed by critic agent; blocker (tee filename collision) and 3 majors (display-claim wording, noise-pattern scoping, exit-code cross-check) fixed with regression tests.

🤖 Generated with Claude Code