Introduction

The context compaction layer of DeepSeek Harness (DSH) is primarily responsible for managing conversational context. Within it, dsh-compaction-basic is responsible for summarizing tool results, which is an expensive model-invocation process. If context overflows but the pressure has not yet reached the summarization threshold, directly summarizing is often unnecessary overhead. The dsh-compaction-micro plugin aims to fill this gap. It acts as a standalone “micro cleanup layer” that, before the official summarization layer, replaces whitelisted rerunnable tool results with placeholders, quickly freeing Token space without invoking a model.

What It Is

This is a micro cleanup layer designed for the DeepSeek Harness compaction flow. It follows the observer pattern: it does not modify model requests and does not initiate model calls; it only triggers compaction events by replacing tool/result content. Each rewrite operation is accompanied by a compaction/prune event, ensuring that persisted logs remain the reconstructable source of truth.

  • Owner: Perfirstvito
  • License: MIT
  • Positioning: A pre-compaction layer activated before the official summarization layer.

Installation and Enablement

Installing this plugin requires using a local link. Run the following command in the plugin directory:

dsh plugin --profile headless add link:<this-dir>

Configuration

This plugin controls cleanup behavior through configuration options. The following are the core configuration items:

Field Default Description
clearableTools [] Whitelist of tools allowed to be cleaned. Only read-only, rerunnable tools are allowed, such as read, glob, grep. If empty, this layer is disabled.
retainRecent 3 Keep the latest N clearable results visible in the context.
microThresholdRatio 0.85 Threshold ratio for triggering cleanup. It triggers when token usage exceeds (contextWindow - reservedTokens) * 0.85.
reservedTokens 0 Number of tokens reserved upfront from the effective context window.
auto true Whether to automatically install listeners. When set to false, only ctx.microCompaction.clearSession() is exposed.

Usage Example

This plugin is usually mounted before dsh-compaction-basic. In the DSH plugin configuration, the recommended order is:

- name: '@deepseek-ai/dsh-token-meter'
- name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
- name: '@deepseek-ai/dsh-compaction-basic'
  config:
    thresholdRatio: 0.9
- name: 'dsh-compaction-micro'
  config:
    clearableTools: [read, glob, grep, web_search, web_fetch]
    retainRecent: 3
    microThresholdRatio: 0.85
    reservedTokens: 0

How It Works

The plugin works via two prepend listeners:

  1. agent/pre-step (prepend):

    • Monitors and measures context pressure.
    • When totalTokens reaches the threshold, that is (contextWindow - reservedTokens) × microThresholdRatio, it clears whitelisted tool results from oldest to newest, while always keeping the most recent retainRecent results visible.
    • After cleanup, the lower layer remeasures the context; if the pressure has been relieved, the expensive summarization step is skipped.

  2. agent/request-error (prepend):

    • When context overflow is confirmed, cleanup is performed first.
    • After cleanup completes, control is delegated to the official backend pruning, summarization, and retry flows.

Notes

  • Mounting Order: Although the listeners are configured with prepend: true, to ensure the correct logical order, it is recommended to mount the dsh-compaction-micro bundle before dsh-compaction-basic.
  • Tool Safety: This plugin is safe only for read-only, rerunnable tools, such as reading files or searching content. Write operations, edits, Shell calls, and similar tools must be removed from the clearableTools whitelist; otherwise, it may cause irreversible data loss.
  • Permissions: The plugin runs with the permissions of the current DSH process. Check the source code and license before use.

Development

For local development, the DSH workspace package needs to be junctioned into the node_modules/@deepseek-ai directory.

npm run typecheck     # TypeScript 类型检查
node --import tsx --test tests/micro.test.ts

Catalog and Repository