Repository navigation
docs(compression): align guide claims with source - #15596
Merged
diegosouzapw merged 7 commits intoOct 6, 2026
Merged
diegosouzapw merged 7 commits into
diegosouzapw merged 7 commits into
Conversation
The Compression Guide's caveman output mode and output-styles passages described behavior the code does not have. Correct them against the current sources: - When to use: the legacy mode is switched by cavemanOutputMode.enabled, which replaces the routing-combo config.auto.outputMode example. A compression combo's Output Mode toggle and the omniroute_set_compression_engine MCP tool's outputMode argument set the same switch. - Back-compat: the mapping to terse-prose applies while outputStyles is empty. The block starts with the [OmniRoute Output Styles] marker; the text matches the legacy injector in en, pt-BR, es, de, fr, it, ru, id and vi, carries one extra space before the boundaries clause in ja and zh, and is English for hu, which terse-prose does not translate. - Boundaries: SHARED_BOUNDARIES keeps code blocks, file paths, commands, errors and URLs exact; terse-prose and terse-cjk add identifiers, and less-code and ponytail add the SAFETY_BOUNDARIES clause. - Auto-Clarity: the content bypass runs while the Auto-Clarity Bypass toggle is on (the default) and is skipped when it is off. The toggle is on the Caveman page's Output Mode card. - How to enable: the dashboard path uses the sidebar labels (Compression Context, Compression Settings).
An accuracy review of the previous commit against the sources found four sentences that were imprecise: - The legacy switch takes effect only while compression itself is on (the master `enabled` flag, off by default), and a non-empty outputStyles selection overrides it. The example now sets both flags, and How to enable states the master-switch requirement for all styles. - "The Terse prose output style injects the same text" read as a comparison with the legacy injector; it now says the same block. - The safety clause less-code and ponytail add can be its translation. - Turning the Auto-Clarity Bypass toggle off skips the keyword check; it does not force injection, which other conditions can still prevent.
…pression-guide-output-mode
A source check of the Compression Guide found statements the code does
not bear out. Correct them against the current sources:
- Caveman Output Mode: requests get the instructions through
applyOutputStyles(), after chatCore.ts resolves the selection with the
back-compat shim; outputMode.ts holds the texts, the content bypass and
the placement helper, and applyCavemanOutputMode() has no production
caller.
- How it works: quote the English full level ("Respond terse like smart
caveman. ...") in place of an example sentence found in no
instruction.
- terse-cjk: the dashboard lists the row by UI locale (zh-CN, zh-TW);
the injector gates it on the resolved request language.
- How injection works: the instructions/input path also covers an empty
messages array, and the content bypass runs on a non-empty one.
- Language selection: autoDetect reads the latest user message with text
and falls back to defaultLanguage, then English.
- Matrix test: locale-gated styles skip the pt-BR requirement, and the
loss check covers the languages BASELINE_LANGUAGES lists.
- Tool Result Compression: list the five strategies compressToolResult()
implements (fileContent, grepSearch, shellOutput, json, errorMessage)
in first-match order, and state that they run as step 1 of the
aggressive engine with a switch each under aggressive.toolStrategies,
all on by default.
- Advanced Compression Systems: drop "that work automatically based on
context"; caveman output mode is opt-in and tool-result compression
runs only in the aggressive engine.
A claim-by-claim verification of the reworked passages against the sources
surfaced statements the code supports only with qualifiers, and a sweep of
the surrounding sections found contradictions the guide had accumulated.
Correct them:
- Advanced intro: name the codex-responses/omniglyph modes the guide does
not cover and tie each section to where it actually runs (tool-result
compression and progressive aging are steps of the aggressive engine,
cache-aware downgrades aggressive/ultra for caching providers, caveman
output mode and output styles are opt-in instructions).
- Caveman Output Mode: instructions ask for terse output, they cannot
guarantee it; the back-compat shim only maps cavemanOutputMode while
outputStyles is empty; input compression still runs after injection.
- Injection: the idempotency check runs before the content bypass; the
order-sensitive bypass is a step word followed within 240 characters by
an action word, not a keyword list; the no-messages path consults
neither the bypass nor the top-level system field, skips an
already-marked instructions field as already_applied, and overwrites
only non-string instructions/input values; a selection that resolves to
no style is skipped as no_styles.
- Terse CJK: only full/ultra answer in Classical Chinese; hiding the
settings row does not clear a saved selection.
- Language selection: autoDetect samples only the messages array, so
Responses bodies fall back to defaultLanguage; the detector returns a
fixed language set and never defaultLanguage on zero hits; vi is never
detected; compression combos force languageConfig on and derive
defaultLanguage from the combo's language packs.
- Style x language matrix: terse-cjk is the only locale-gated style, and
KNOWN_ENGLISH_ONLY may hold only styles with no translations at all.
- Tool Result Compression: spell out each strategy's trigger (the
indentation-tolerant code keywords, the path:line: shape that a
timestamp line also matches, ANSI CSI or "$" + whitespace, the JSON
start/parse conditions, the case-insensitive error substrings), the
{...N keys} placeholder for nested arrays, the 14-line floor of the
error elision marker, and the callers' saved <= 0 guard that keeps the
original while the fallback summarizer still shortens long tool
messages.
- Ultra Mode: it is an independent score-based prose pruner with
structure preservation and an optional SLM tier - it does not include
Aggressive mode's features, thin code blocks, or binary-search
truncate.
- Aggressive Mode: tool outputs are truncated or elided, not summarized.
- Cache-Aware: a caching provider alone triggers the downgrade, no
cache_control markers required; drop the never-consumed
deterministic-transformations step and add the targetFormat field to
the example.
- Progressive Aging: document the shipped thresholds (last 2 turns
verbatim, caveman at distance 3, summarized from distance 4, nothing
dropped) and that it runs in aggressive mode only, not ultra.
- Stacked Pipeline: compose the numbers from the guide's own math (46%
Caveman step, ~89% average) and point configuration at the
stackedPipeline setting or a named compression combo, not an
auto-combo modePack.
- Combo Overrides: compressionOverride is a plain mode string, and
caching providers are handled by the always-on cache-aware adjustment
(there is no selectable cache-aware mode); weights and modePack sit at
the top level of combo config.
- RTK: 55 built-in filters, not 49. Configuration: the routing-combo
override dropdown also offers Codex Responses.
diegosouzapw
merged commit Oct 6, 2026
5a4b681
into
diegosouzapw:release/v3.8.52
44 of 51 checks passed
3 of 5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/compression/COMPRESSION_GUIDE.mdfound statements the code does not bear out. This PR corrects the Caveman Output Mode, Output Styles, Tool Result Compression and language-selection passages against the current sources, and fixes the contradictions a verification sweep found in the surrounding sections (Ultra, Aggressive, Cache-Aware, Progressive Aging, Stacked Pipeline, Combo Overrides, RTK filter count, routing-combo override list).Main corrections:
applyOutputStyles()afterchatCore.tsresolves the selection with the back-compat shim;outputMode.tsholds the texts, the bypass and the placement helper, and itsapplyCavemanOutputMode()has no production caller. The example prompt that matches no instruction text is replaced with the actual Englishfulltext. The shim mapscavemanOutputModetoterse-proseonly whileoutputStylesis empty, and input compression still runs after injection.systemfield, skips an already-markedinstructionsfield asalready_applied, and overwrites only non-stringinstructions/inputvalues.autoDetectsamples only themessagesarray, so Responses bodies (input) fall back todefaultLanguage; the detector returns a fixed language set and neverdefaultLanguageon zero hits;viis never detected; a compression combo forceslanguageConfig.enabledon and derivesdefaultLanguagefrom the combo's language packs.path:line:shape a timestamp line also matches, ANSI CSI or$+ whitespace, JSON start/parse conditions, case-insensitive error substrings), plus the{…N keys}placeholder, the error-elision marker's 14-line floor, and the callers'saved <= 0guard.cache_controlmarkers required, and markers alone never trigger it); the never-consumed deterministic-transformations step is dropped.stackedPipelinesetting or a named compression combo, not an auto-combomodePack.compressionOverrideis a plain mode string; caching providers are handled by the always-on cache-aware adjustment (there is no selectablecache-awaremode);weights/modePacksit at the top level of combo config.Related Issues
Validation
npm run check:docs-all(includes the fabricated-docs gate) — passesnpm run lintnot applicable to a markdown-only diff; prettier appliedrelease/v3.8.52Every changed passage was verified claim-by-claim against the source, with evidence recorded per claim (file, line, quote).
release/v3.8.52was red before this branch; the inherited failures are not from this change)Note: the 66 i18n mirrors of this guide wait for the next refresh.
Tests Added Or Updated
Coverage Notes
Reviewer Notes
src/i18n(66 locales) are refreshed in bulk and intentionally not touched here.