dsh-compaction-instant

Configuration

All fields optional; defaults shown.

Key	Default	Meaning
thresholdRatio	0.5	Fraction of the routed model's context window that triggers automatic compaction
retainTurns	1	Preferred complete recent turns kept verbatim (automatic and manual /compact); never overrides the ceiling
retainTokens	5120	Hard retained-region token ceiling: older whole turns are added only while the total fits, and when the latest turn alone exceeds it, only the fitting suffix of that turn is kept
auto	true	Register agent/pre-step pressure and agent/request-error overflow recovery
checkpointCap	65536	Total budget for one compiled checkpoint (compiler tokens): a checkpoint compiled from a smaller span stays near-lossless, a larger one elides down to this cap
maxTokens / checkpointScale	8192 / 0.1	Deprecated — accepted for drop-in compatibility but ignored: the budget is the cap alone (no floor, no proportional scaling)
textTokens	512	Budget per assistant text block
userTextTokens	1024	Budget per user text block
toolCallTokens	128	Budget per tool-call one-liner (never rescaled — see the elision rules)
toolResultExcerptTokens	256	Accepted for compatibility; inert — tool results no longer occupy entries
includeReasoning	false	Keep reasoning blocks in the checkpoint
stripNoiseXml	true	Strip configured noise wrappers from user text
noisePatterns	see compiler	Noise XML regex sources, applied with the s flag
toolKeyFields	built-ins	Extra tool-name → argument-field map for one-liners
toolArgTools	see compiler	Whitelist whose key argument renders in the one-liner (read/write/edit/glob/grep/bash/shell/web_search/skill/subagent/…); every other tool is name-only
hideTools	—	Bookkeeping tools dropped from the checkpoint entirely
modelPolicies	—	Per provider/model overrides of thresholdRatio/retainTurns/retainTokens
compactionRetries / maxOverflowRetries	1 / 1	Retry budgets, same semantics as basic
summarizationProvider / summarizationModel	—	Accepted for config drop-in compatibility; inert — this backend never routes a model

The tool and command plugins each take their own { maxRecallTokens?: 16000, maxSearchHits?: 50 } config.

Cordis config gotcha: the plugin row's config passes through the schemastery schema, whose ~standard adapter injects [] for every absent array key (toolArgTools, hideTools, noisePatterns, toolKeyFields, modelPolicies). The resolver treats an empty list as unset and falls back to the defaults — so a missing toolArgTools keeps the built-in whitelist (never disable it by writing toolArgTools: []; empty means default). debug: true writes per-compile diagnostics to the configured debugLogPath (default $DSH_HOME/compaction-debug.log).

Budgets are enforced twice — by token count and by a budget × 4 character ceiling — so pathological unbroken runs (base64 blobs, minified files) cannot bypass them. Tool calls are always one line: they are never rescaled, and the cap loop shrinks only the conversation-text budgets (floor 32 tokens each). If the compiled region still exceeds the cap, the oldest tool rows are removed first ([N tool/result entries elided: seqs a-b]), and only then the oldest remaining entries ([N earlier entries elided: seqs a-b]) — tool calls can never squeeze the dialogue out. The newest content always survives.

Browser settings card (Settings → Plugins)

Since 0.1.4 the engine exposes a user-owned settings namespace (compaction-instant) on every deployment that composes the settings domain (the standard web/desktop profiles do). The editable subset, persisted to settings.yaml and layered over the plugin row's cordis config:

Field	Meaning
checkpointCap	Total compiler-token budget for one checkpoint (default 65536)
auto	Register automatic between-step compaction
thresholdRatio	Context-window fraction that triggers automatic compaction (default 0.5)
retainTurns	Preferred complete recent turns kept verbatim (default 1)
retainTokens	Hard retained-token ceiling: whole turns (or, when the latest turn is larger, a fitting suffix of it) never exceed it (default 5120)

Everything else (modelPolicies, toolArgTools, debug, debugLogPath, the deprecated maxTokens/checkpointScale, …) stays cordis-config-only. The settings layer never breaks the engine: every settings write is re-validated by the full config resolver before it is persisted, and non-exposed entry fields keep their composed values. Without a settings service the engine behaves exactly as before (composition entry only). The card is registered on the client bundle, so it appears without touching any deployment config beyond installing the package — restart dsh web once so the boot graph picks up the dsh.client bundle.

Tokenizer and multilingual behavior

The tokenizer is a character-class heuristic: ASCII letter runs and digit runs count as one token each, punctuation is per-character, whitespace is free, and every other code unit is its own token. Concretely:

Content	Tokens
CJK (你好，世界！)	1 per code point (6)
Cyrillic / Arabic	1 per code unit
Accented Latin (café)	ASCII runs stay grouped (caf + é)
Emoji (😀)	2 (surrogate pair)

Every truncation, excerpt, and cap cut is taken at a code-point boundary — a slice never leaves a lone surrogate half, so emoji and other astral characters always reach the model intact (pinned by test/multilang.test.js). The character-density ceiling follows the DeepSeek docs conversion (quick_start/token_usage): about 0.3 tokens per non-CJK character and 0.6 per CJK character.

The harness token meter (used for the shrink guarantee and /compact reporting) is a separate chars / 4 + block overhead estimator; the two deliberately coexist — see the top-level design notes.

Method 3 — Direct install + manual preset configuration

dsh plugin --profile web add dsh-compaction-instant
mkdir -p "$DSH_HOME/.agent-presets/"