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
retainRatio	0.05	Fraction of the context window kept verbatim at the surface tail
retainTokens	—	Exact tail budget; mutually exclusive with retainRatio
manualRetainRatio	0.05	Fraction of the measured surface kept verbatim by a manual /compact (so the recent conversation is never compiled away)
manualRetainTokens	—	Exact manual tail budget; mutually exclusive with manualRetainRatio
auto	true	Register agent/pre-step pressure and agent/request-error overflow recovery
maxTokens	8192	Floor of the total cap for one compiled checkpoint (density-aware tokens)
checkpointScale	0.1	The effective cap is max(maxTokens, shadowed × checkpointScale), ceilinged at checkpointCap — a large span never crushes every entry into a sliver
checkpointCap	65536	Absolute ceiling of the scaled checkpoint cap
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/retain* (basic-compatible shape)
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 (scaled) 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
checkpointScale	Checkpoint budget = shadowed tokens × this ratio
checkpointCap	Absolute ceiling of the scaled budget
maxTokens	Total compiler-token cap for one checkpoint
auto	Register automatic between-step compaction
debug	Write engine debug lines to the log file
debugLogPath	Debug log path (empty = $DSH_HOME/compaction-debug.log)

Everything else (modelPolicies, toolArgTools, …) 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 uses UTF-16 length, which is the conservative side for astral content.

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/"