feat(eval): /eco token-compression benchmark — measured, README showcase

.gitignore

@@ -139,6 +139,12 @@ out/
 /eval/runs/
 /eval/__pycache__/
 
+# /eco benchmark — captured command outputs are machine-specific (and the
+# macOS `log show` capture carries local system-log lines); regenerate with
+# eval/eco/capture_corpus.py. The measured results/ tables ARE tracked.
+/eval/eco/corpus/
+/eval/eco/__pycache__/
+
 # Stray *.patch / *.diff artifacts the agent occasionally writes via its
 # Write tool during SWE-bench eval (we disable Write/Edit in the wrapper
 # now but old artifacts may persist).

README.md

@@ -147,6 +147,125 @@ Reproduce locally — see [`eval/README.md`](eval/README.md) for the full workfl
 
 ***
 
+## 🌿 `/eco` Token Compression — **-80% Bash-output tokens, measured**
+
+Long agentic sessions drown in tool output: failing test logs, `git` progress spam,
+2,000-line listings. Toggle **`/eco`** on and ClawCodex compresses the *model-bound
+rendering* of every Bash result with deterministic filters ported from
+[RTK](https://github.com/rtk-ai/rtk)'s method set — failure-focused test summaries,
+command-scoped ceremony stripping, log deduplication with `[×N]` counts, and a
+recoverable head-cap — while the full raw output stays on disk behind a runnable
+recovery hint. No model in the loop, no command rewriting, nothing to learn.
+
+```text
+$ pytest        # 128 lines → 37 lines, 1,347 → 390 tokens (-71%)
+Pytest: 5 failed, 29 passed in 0.04s
+
+1. [FAIL] test_unknown_sku_message
+   with pytest.raises(OrderError, match="unknown sku 'gold-bar'"):
+   >           o.total()
+   tests/test_orders.py:34:
+   ⋮
+5. [FAIL] test_truncate_one
+   >       assert truncate_words("alpha beta", 1) == "alpha..."
+   E       AssertionError: assert 'alpha beta...' == 'alpha...'
+[full output: ~/.clawcodex/<ws>/<session>/eco/1707_pytest.log]
+Command failed with exit code 1
+```
+
+**Measured, not estimated.** RTK's README models a 30-minute session and *estimates*
+-80%. We ran the experiment instead: a 27-operation corpus of **real command
+outputs** — failing `pytest`/`go test`/`jest` runs, `pip`/`npm` installs, git
+workflows, repo-scale listings, a 34,000-line system log, captured live (RTK's own
+"never synthetic" fixture rule) — replayed through the exact production pipeline,
+counting tiktoken `cl100k_base` tokens of the model-bound text with `/eco` off vs on:
+
+| Operation | Filter | Raw tokens | `/eco` tokens | Saved |
+|---|---|---:|---:|---:|
+| `pytest` (failing run) | failure focus | 1,347 | 390 | **-71%** |
+| `pytest -v` (failing run) | failure focus | 1,925 | 392 | **-79%** |
+| `pytest -v` (green run) | one-line collapse | 359 | 60 | **-83%** |
+| `go test -v ./...` (failing run) | failure focus | 527 | 227 | **-56%** |
+| `npx jest` (failing run) | failure focus | 444 | 175 | **-60%** |
+| `npm install jest` | ceremony strip | 188 | 8 | **-95%** |
+| `pip install flask` | ceremony strip | 514 | 85 | **-83%** |
+| `git clone --progress` | ceremony strip | 6,868 | 18 | **-99%** |
+| `git push --progress` | ceremony strip | 6,458 | 75 | **-98%** |
+| `git status` (dirty tree) | advice strip | 143 | 91 | **-36%** |
+| `git log -n 300` | recoverable head-cap | 7,714 | 946 | **-87%** |
+| `git diff v1.0.0..v1.1.0 -- src` | recoverable head-cap | 7,561 | 748 | **-90%** |
+| `ls -R src` | recoverable head-cap | 9,088 | 225 | **-97%** |
+| `cat` (900-line file) | recoverable head-cap | 6,833 | 552 | **-91%** |
+| `grep -rn 'def ' src/` | recoverable head-cap | 7,582 | 1,219 | **-83%** |
+| `log show --last 90s` (34k lines) | log dedup | 10,512 | 1,977 | **-81%** |
+| **Whole corpus (27 operations)** | | **92,989** | **17,767** | **-80%** |
+
+The corpus also includes 8 operations that (correctly) pass through **byte-identical**
+— a clean `git status`, `docker ps`, `ruff check` findings, a small failing `go test`,
+a 370-line `grep` that sits under the head-cap threshold — because `/eco` guarantees
+**never worse**: a compression that doesn't beat the raw rendering is discarded.
+Full tables: [`eval/eco/results/results.md`](eval/eco/results/results.md).
+
+<details>
+<summary><b>vs RTK's own 30-minute-session model</b> (why our headline is honest)</summary>
+
+<br>
+
+RTK *rewrites commands* into its own CLI (`rtk ls`, `rtk read`, `rtk grep`), so every
+operation in its session model compresses. `/eco` deliberately compresses **results
+only** — the command the model wrote is the command that runs — and small outputs pass
+through untouched. Recomputing RTK's session table with our *measured* ratios (0%
+where our corpus shows passthrough at RTK's assumed sizes):
+
+| Operation | Freq | Standard | rtk (estimated) | clawcodex `/eco` (measured) |
+|---|---:|---:|---:|---:|
+| `ls` / `tree` | 10x | 2,000 | 400 | 2,000 (0%) |
+| `cat` / read | 20x | 40,000 | 12,000 | 40,000 (0%) |
+| `grep` / `rg` | 8x | 16,000 | 3,200 | 16,000 (0%) |
+| `git status` | 10x | 3,000 | 600 | 1,908 (-36%) |
+| `git diff` | 5x | 10,000 | 2,500 | 10,000 (0%) |
+| `git log` | 5x | 2,500 | 500 | 2,500 (0%) |
+| `git add/commit/push` | 8x | 1,600 | 120 | 1,007 (-37%) |
+| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | 9,850 (-60%) |
+| `ruff check` | 3x | 3,000 | 600 | 3,000 (0%) |
+| `pytest` | 4x | 8,000 | 800 | 2,320 (-71%) |
+| `go test` | 3x | 6,000 | 600 | 6,000 (0%) |
+| `docker ps` | 3x | 900 | 180 | 900 (0%) |
+| **Total** | | **~118,000** | **~23,900 (-80%)** | **~95,500 (-19%)** |
+
+Under RTK's *averaged* assumptions (every `cat` ≈ 2,000 tokens, every `ls` ≈ 200) the
+honest number for a results-only compressor is **-19%** — those mid-size outputs are
+exactly what ClawCodex already handles with Read-tool line caps and 30k-char Bash
+truncation. But real sessions aren't averages: they're fat-tailed, and one 2,000-line
+`git log`, one failing suite, or one `npm install` blows more context than fifty small
+commands. `/eco` targets precisely that tail — which is why the measured number on
+real outputs is **-80%**, the same figure RTK estimates, with none of the risk of
+rewriting commands.
+
+</details>
+
+**The RTK safety rules, kept** (see [`src/eco/`](src/eco/)):
+
+- **Never worse** — every compressed rendering is token-checked against the exact
+  baseline it replaces; the baseline wins ties. Worst case is 0% saved, never negative.
+- **Failures survive** — error/failure lines are never rewritten, only ceremony drops;
+  a green summary with a non-zero exit code is treated as untrusted and passed through.
+- **Everything recoverable** — lossy compressions tee the full output to the session
+  dir and append a runnable hint (`[see remaining: tail -n +61 …]`); no tee, no compression.
+- **Semantics untouched** — exit codes, `is_error`, images, background tasks, and
+  interrupted runs are never altered; any filter exception falls back to passthrough.
+
+`/eco status` shows per-filter savings for the session. Compression stacks with the
+[DeepSeek prefix cache](#-deepseek-prefix-cache): the cache makes the stable prefix
+nearly free, `/eco` shrinks the fresh suffix every turn actually pays for. Reproduce:
+
+```bash
+python3 eval/eco/capture_corpus.py --workdir /tmp/eco-bench   # capture real outputs
+.venv/bin/python eval/eco/measure.py                          # replay + count tokens
+```
+
+***
+
 ## ⭐ Star History
 
 [View star history on star-history.com](https://www.star-history.com/?repos=agentforce314%2Fclawcodex&type=date&legend=top-left)
@@ -476,6 +595,7 @@ clawcodex --help           # All flags: -p, --provider, --model, …
 | `/skill` | Skill launcher flow |
 | `/context` | Workspace / prompt context (when available) |
 | `/compact` | Compact or clear conversation (fallback clears if compact unavailable) |
+| `/eco` | Toggle Bash-output token compression (`on` / `off` / `status` for per-filter savings) |
 | `/exit`, `/quit`, `/q` | Exit |
 
 ### Skills (Slash Commands)

docs/i18n/README_AR.md

@@ -57,6 +57,28 @@
 
 ***
 
+## 🌿 ضغط التوكنات `/eco` — **‏-80% مُقاسة على مخرجات Bash**
+
+فعّل **`/eco`** وسيضغط ClawCodex العرض المُرسل إلى النموذج لكل نتيجة Bash عبر
+مرشّحات حتمية منقولة من [RTK](https://github.com/rtk-ai/rtk): ملخّصات اختبارات تركّز
+على الإخفاقات، إزالة الضجيج الشكلي (`git`/`pip`/`npm`)، إزالة تكرار السجلات، وقصّ
+قابل للاسترجاع — بينما يبقى الناتج الخام كاملًا على القرص خلف تلميح قابل للتنفيذ
+مباشرة. ضمان **لا أسوأ أبدًا**: أي ضغط لا يتفوّق على العرض الخام يُستبعد، وأسطر
+الأخطاء تبقى دائمًا.
+
+مُقاس (توكنات tiktoken ‏`cl100k_base`) على 27 عملية حقيقية أُعيد تشغيلها عبر خطّ
+الإنتاج:
+
+| العملية | خام | `/eco` | التوفير |
+|---|---:|---:|---:|
+| `pytest` (مع إخفاقات) | 1,347 | 390 | **-71%** |
+| `git clone --progress` | 6,868 | 18 | **-99%** |
+| `ls -R src` | 9,088 | 225 | **-97%** |
+| `log show --last 90s` (34 ألف سطر) | 10,512 | 1,977 | **-81%** |
+| **كامل المجموعة (27 عملية)** | **92,989** | **17,767** | **-80%** |
+
+الجداول الكاملة والمنهجية: [`eval/eco/`](../../eval/eco/README.md).
+
 ## ⭐ Star History
 
 <a href="https://www.star-history.com/?repos=GPT-AGI%2FClaw-Codex&type=date&legend=top-left">

docs/i18n/README_FR.md

@@ -57,6 +57,29 @@
 
 ***
 
+## 🌿 Compression de tokens `/eco` — **-80 % mesurés sur la sortie Bash**
+
+Activez **`/eco`** et ClawCodex compresse le rendu côté modèle de chaque résultat Bash
+avec des filtres déterministes portés de [RTK](https://github.com/rtk-ai/rtk) : résumés
+de tests focalisés sur les échecs, suppression du cérémonial (`git`/`pip`/`npm`),
+déduplication de logs et troncature récupérable — la sortie brute complète reste sur
+disque derrière un indice directement exécutable. Garantie **jamais pire** : une
+compression qui ne bat pas le rendu brut est abandonnée, et les lignes d'erreur
+survivent toujours.
+
+Mesuré (tokens tiktoken `cl100k_base`) sur 27 opérations réelles rejouées à travers le
+pipeline de production :
+
+| Opération | Brut | `/eco` | Gain |
+|---|---:|---:|---:|
+| `pytest` (échecs) | 1,347 | 390 | **-71%** |
+| `git clone --progress` | 6,868 | 18 | **-99%** |
+| `ls -R src` | 9,088 | 225 | **-97%** |
+| `log show --last 90s` (34k lignes) | 10,512 | 1,977 | **-81%** |
+| **Corpus complet (27 opérations)** | **92,989** | **17,767** | **-80%** |
+
+Tables complètes et méthodologie : [`eval/eco/`](../../eval/eco/README.md).
+
 ## ⭐ Star History
 
 <a href="https://www.star-history.com/?repos=GPT-AGI%2FClaw-Codex&type=date&legend=top-left">

docs/i18n/README_HI.md

@@ -57,6 +57,28 @@
 
 ***
 
+## 🌿 `/eco` टोकन संपीड़न — **Bash आउटपुट पर मापा गया -80%**
+
+**`/eco`** चालू करें और ClawCodex हर Bash परिणाम की मॉडल-बाउंड रेंडरिंग को
+[RTK](https://github.com/rtk-ai/rtk) से पोर्ट किए गए नियतात्मक फ़िल्टरों से संपीड़ित
+करता है: विफलता-केंद्रित टेस्ट सारांश, औपचारिक शोर हटाना (`git`/`pip`/`npm`), लॉग
+डीडुप्लीकेशन और पुनर्प्राप्ति-योग्य ट्रंकेशन — पूरा कच्चा आउटपुट एक चलाने-योग्य संकेत के
+पीछे डिस्क पर सुरक्षित रहता है। **कभी बदतर नहीं** की गारंटी: जो संपीड़न कच्ची रेंडरिंग से
+बेहतर नहीं, वह छोड़ दिया जाता है, और त्रुटि पंक्तियाँ हमेशा बची रहती हैं।
+
+उत्पादन पाइपलाइन से दोहराए गए 27 वास्तविक ऑपरेशनों पर मापा गया (tiktoken
+`cl100k_base` टोकन):
+
+| ऑपरेशन | कच्चा | `/eco` | बचत |
+|---|---:|---:|---:|
+| `pytest` (विफलताओं सहित) | 1,347 | 390 | **-71%** |
+| `git clone --progress` | 6,868 | 18 | **-99%** |
+| `ls -R src` | 9,088 | 225 | **-97%** |
+| `log show --last 90s` (34k पंक्तियाँ) | 10,512 | 1,977 | **-81%** |
+| **पूरा कॉर्पस (27 ऑपरेशन)** | **92,989** | **17,767** | **-80%** |
+
+पूर्ण तालिकाएँ और कार्यप्रणाली: [`eval/eco/`](../../eval/eco/README.md)।
+
 ## ⭐ Star History
 
 <a href="https://www.star-history.com/?repos=GPT-AGI%2FClaw-Codex&type=date&legend=top-left">

docs/i18n/README_PT.md

@@ -57,6 +57,29 @@
 
 ***
 
+## 🌿 Compressão de tokens `/eco` — **-80% medidos na saída do Bash**
+
+Ative **`/eco`** e o ClawCodex comprime a renderização enviada ao modelo de cada
+resultado do Bash com filtros determinísticos portados do
+[RTK](https://github.com/rtk-ai/rtk): resumos de testes focados nas falhas, remoção de
+cerimônia (`git`/`pip`/`npm`), deduplicação de logs e truncamento recuperável — a saída
+bruta completa fica em disco atrás de uma dica executável. Garantia **nunca pior**: uma
+compressão que não supera a renderização bruta é descartada, e linhas de erro sempre
+sobrevivem.
+
+Medido (tokens tiktoken `cl100k_base`) em 27 operações reais reproduzidas pelo pipeline
+de produção:
+
+| Operação | Bruto | `/eco` | Ganho |
+|---|---:|---:|---:|
+| `pytest` (com falhas) | 1,347 | 390 | **-71%** |
+| `git clone --progress` | 6,868 | 18 | **-99%** |
+| `ls -R src` | 9,088 | 225 | **-97%** |
+| `log show --last 90s` (34k linhas) | 10,512 | 1,977 | **-81%** |
+| **Corpus completo (27 operações)** | **92,989** | **17,767** | **-80%** |
+
+Tabelas completas e metodologia: [`eval/eco/`](../../eval/eco/README.md).
+
 ## ⭐ Star History
 
 <a href="https://www.star-history.com/?repos=GPT-AGI%2FClaw-Codex&type=date&legend=top-left">

docs/i18n/README_RU.md

@@ -57,6 +57,29 @@
 
 ***
 
+## 🌿 Сжатие токенов `/eco` — **-80% на выводе Bash, измерено**
+
+Включите **`/eco`**, и ClawCodex сжимает отправляемое модели представление каждого
+результата Bash детерминированными фильтрами, портированными из
+[RTK](https://github.com/rtk-ai/rtk): сводки тестов с фокусом на падениях, срезание
+церемониального шума (`git`/`pip`/`npm`), дедупликация логов и восстановимое усечение —
+полный сырой вывод остаётся на диске за исполняемой подсказкой. Гарантия **никогда не
+хуже**: сжатие, не превосходящее сырой вывод, отбрасывается, а строки ошибок всегда
+сохраняются.
+
+Измерено (токены tiktoken `cl100k_base`) на 27 реальных операциях, проигранных через
+производственный конвейер:
+
+| Операция | Сырой | `/eco` | Экономия |
+|---|---:|---:|---:|
+| `pytest` (с падениями) | 1,347 | 390 | **-71%** |
+| `git clone --progress` | 6,868 | 18 | **-99%** |
+| `ls -R src` | 9,088 | 225 | **-97%** |
+| `log show --last 90s` (34k строк) | 10,512 | 1,977 | **-81%** |
+| **Весь корпус (27 операций)** | **92,989** | **17,767** | **-80%** |
+
+Полные таблицы и методология: [`eval/eco/`](../../eval/eco/README.md).
+
 ## ⭐ Star History
 
 <a href="https://www.star-history.com/?repos=GPT-AGI%2FClaw-Codex&type=date&legend=top-left">