In the plugin ecosystem of DeepSeek Harness (DSH), when handling long conversation contexts, the compaction strategy determines system stability and inference cost. The built-in compaction-basic in DSH is a basic implementation. If a Reasonix-like cache-aware compaction logic is needed, dsh-compaction-cacheaware can be used. This is an independent, modular DSH plugin that implements the official ctx.compaction interface.

Plugin Positioning and Features

This plugin is intended to provide a Reasonix-style backend for DSH. It does not modify other plugins, presets, or host files; instead, it replaces the default compaction behavior through mounting.

Core capabilities include:
* Reasonix-style design: Implements the core logic of cache-aware compaction.
* Modular implementation: Only registers ctx.compaction and its automatic listeners, without interfering with other components.
* Official interface integration: Implements the ctx.compaction interface from @deepseek-ai/dsh-compaction.
* Automatic synchronization: Supports automatically syncing design updates from esengine/DeepSeek-Reasonix.
* Single trigger mechanism: Uses only compact_ratio (default 0.85) as the automatic trigger condition.
* Structured checkpoint: Generates structured checkpoints containing a stable prefix, summary, and recent tail.
* Realm self-check: Has a Realm self-check mechanism to prevent race conditions within the same realm.
* Non-invasiveness: After installation, it does not affect existing plugin, preset, or host file configuration.

Installation

The plugin has been published to the npm registry. Installation via pnpm is recommended.

  1. Enter the DSH profile directory:
    cd "$env:USERPROFILE\.dsh\profiles\web"
  1. Run the installation command:
    pnpm add dsh-compaction-cacheaware

You can also install it directly from GitHub:

pnpm add dsh-compaction-cacheaware@github:Zhuchen00123/dsh-compaction-cacheaware

Configuration and Enabling

After installation, you need to mount this plugin in the compaction realm of the preset to replace the default compaction-basic.

Note: Profile-level bundle patches cannot override the isolated compaction realm inside Agent presets, so it must be configured manually in each preset.

Configuration Example

In the YAML configuration of the Agent preset, replace compaction-basic with dsh-compaction-cacheaware:

- id: compaction-cacheaware
  name: 'dsh-compaction-cacheaware'
  config:
    compactRatio: 0.85
    checkpointCeilingRatio: 0.5
    recentTailRatio: 0.1
    recentTailMinTokens: 8192
    recentTailMaxTokens: 16384
    summaryMaxTokens: 16384

At the same time, @deepseek-ai/dsh-command-compact needs to be placed in the same realm so that the /compact command can use this backend.

Configuration Parameters

Key Default Meaning
compactRatio 0.85 The only automatic trigger threshold, determining the point at which context compaction is triggered.
checkpointCeilingRatio 0.5 The threshold ceiling accepted for normal automatic checkpoints.
recentTailRatio 0.1 The ratio of the recent original tail that is retained.
recentTailMinTokens 8192 The lower bound of the generated tail.
recentTailMaxTokens 16384 The upper bound of the generated tail.
summaryMaxTokens 16384 The output limit for the summarization generator.
exceptionalMinSavingsRatio 0.25 The minimum savings ratio required when the fixed prefix exceeds the threshold.
minRecentKeep 2 The minimum number of messages to keep recently.
minCompactMessages 2 The minimum number of messages that can be compacted.
maxPinnedFirstUserTokens 1500 The token limit for pinned first-turn user messages.
pinnedFirstUserWindowFrac 0.15 The fractional upper bound for the first-user pinned window.
protocolReserveTokens 256 Reserved protocol tokens.
summarizationProvider / summarizationModel '' Optional summarization routing; uses the conversation routing by default.
auto true Register automatic pressure/overflow listeners.

Notes

  • Runtime environment: Requires Node.js version >= 22.
  • License: MIT.
  • Non-invasiveness: The plugin does not modify other plugins or host files such as dsh-wsl-bash, dsh-team-dashboard, etc.
  • Isolated realm limitation: Profile-level bundle patches cannot directly apply to the isolated compaction realm of Agent presets. If a preset already includes compaction-basic, that preset must be migrated separately to use this plugin.

Summary

dsh-compaction-cacheaware provides DSH with a structurally designed compaction backend migrated from Reasonix. Through a single trigger mechanism and structured checkpoint design, it optimizes the processing workflow for long contexts. Developers can enable this capability in Agent presets with a simple replacement.

For details and source code, please refer to the GitHub repository.