dsh-compaction-control
One panel for DeepSeek Harness automatic context compaction: trigger and
retained-tail sliders, a model-callable compact_now tool, idle-only handoff,
and an optional zero-token deterministic summarizer.
DSH ships a solid compaction engine (@deepseek-ai/dsh-compaction-basic) whose
parameters are fixed: one trigger ratio, one retained tail, and always a model
call to write the summary. This plugin puts four independently-useful controls
behind one switch panel instead of four separate plugins.
Features
| Control | What it does |
|---|---|
| Trigger threshold (17–90%) | Percentage of the routed model's context window at which automatic compression starts. Default 80%. |
| Tail kept (1–89%) | How much of the message budget survives verbatim — it is a retained fraction, so larger means less compression. The older part folds into the summary. |
| Automatic compression | Off disables pressure-driven compression entirely. Manual compression still works. |
| Model scheduling | Registers a compact_now tool so the model can request compression itself when it changes topic or the window is nearly full. |
| Idle handoff | A request made mid-turn is parked and replayed once the agent is idle, so compression never interrupts work in progress. |
| Deterministic compression | Replaces the summarization model call with code: zero tokens, byte-identical output for the same span. |
Install
Install the bundle into your DSH profile and enable it:
plugin_manager install_bundle target=<path-to-this-directory>
Then open Settings → Compaction and adjust. Changes take effect on Save, and they persist across restarts.
How it works
The engine is mounted inside an agent preset's isolate group, not as a profile
row, so a profile patch cannot reach its thresholdRatio without restating the
whole preset — and ctx.get('compaction') resolves to nothing outside that
isolation realm. Two engine properties make a live override safe instead:
- it re-reads
this.configon every decision, and resolveConfigreturns a frozen snapshot,
so replacing the reference on the live instance takes effect on the next check,
with no restart. The plugin walks ctx.registry → fiber stores to find each
mounted engine.
Two values beyond the percentages are set for correctness:
headroomTokensis pushed far below zero. The shipped pressure formula caps the threshold atcontextWindow − reservedCompletionTokens − headroomTokens, and a route declaring a largemaxTokens(128 000 is common) would otherwise pin that cap under the slider, leaving its upper half inert. A negative headroom cancels the reservation so the percentage is the only deciding term. The summarizer's own output cap is restated separately.retainTokensis cleared, because it would otherwise win over the retained percentage in the resolver.
Which sessions a change affects
Engine count is not session count: engines are mounted per agent preset,
not per conversation. A change applies globally — to running conversations at
their next agent/pre-step, and to presets loaded later once their first agent
appears. Already-compressed history is untouched; the setting decides the
next trigger point.
Saving and persistence
There is a real Save button. Editing only changes the form; pressing Save
writes every pending change in one request through the DSH configEditor into
the profile's cordis.patch.yml, so settings survive a restart.
One detail: when a written value equals the bundle default, the configEditor
prunes the profile row as redundant. That is why this plugin's row is absent at
defaults and appears once a value moves — "not overridden" and "overridden to
the same value" are treated as one. If a future version changes a factory
default, an unpinned value follows it; an explicitly overridden value does not.
Compatibility
| DSH version | Status |
|---|---|
| 0.2.2-rc.2 | tested |
| 0.2.2-rc.3 | tested |
engines.dsh is >=0.2.2-rc.2 <0.3.0-0. The plugin depends on these stable
APIs: the compaction service contract, agent/pre-step (waterfall),
agent/status, agent/created, session/event, loader/volatile-update,
webServer.register, tools.register, and configEditor.edit.
Limitations
- Requires a mounted
@deepseek-ai/dsh-compaction-basicengine. With another backend, or compaction disabled, the sliders report that no engine was found and stay inert. - Settings reach the presets loaded now; a preset selected later is picked up shortly after its first agent appears.
- The compaction history on the page is kept in process memory and is not written to the session log — the session log keeps its own authoritative record of every compression.
- The deterministic summarizer is a code extraction, not a semantic summary. It preserves hard facts and the shape of the conversation but cannot infer intent that was never written down.
License
MIT
No comments yet. Be the first to write one.