Introduction

In the agent development workflow of DeepSeek Harness (DSH), long text results returned by tool executions continuously accumulate and quickly fill the model context window. The dsh-token-optimizer plugin provides a deterministic, recoverable compression mechanism for handling these redundant results and controlling token consumption.

What Is This

This is a plugin maintained by Snow-ea, designed to provide deterministic, recoverable tool result compression and cache-aware compression for DeepSeek Harness. It acts as a root-level adapter that manages compression logic and provides a Web visualization interface.

Core Features

  • Tool result compression: Compresses results before they repeatedly enter the model context.
  • PTC log compression: Compresses sub-dispatch log copies without changing the complete structured values received by the run_code program.
  • Recoverable archives: Archives all lossy replacements and provides precise, session-authorized recovery through the retrieve_spill interface.
  • Root-level adapter: Provides a root-level BasicCompactionEngine adapter with a default compression ratio of 62.5%, while preserving DSH’s cache-aware replay, Session API, and routing image accounts.
  • Web dashboard: Provides a Web conversation dashboard through separate Conversation, Renderer, and Session client contracts.

Installation and Enablement

The plugin depends on DeepSeek Harness 0.2.0-rc.2. Install it under the Web profile:

dsh plugin --profile web add dsh-token-optimizer@0.2.3

After installation, you must restart any existing dsh web process. The installation package enables recovery, projection, the Web dashboard, and the 62.5% automatic compression engine in all four agent modes.

Typical Usage

The plugin’s early compression is controlled by the boolean value compaction (enabled by default).

  1. Disable early compression:
    - id: dsh-token-optimizer
      config:
        compaction: false

After disabling, tool result compression, `retrieve_spill`, session projection, and the dashboard remain active, but the root-level `ctx.compaction` provider and pressure/spill listeners are deregistered.
  1. Adjust compression thresholds:
    - id: dsh-token-optimizer
      config:
        thresholdRatio: 0.5
        retainRatio: 0.16

Note: `retainRatio` must be strictly lower than `thresholdRatio`; otherwise, the upstream engine will refuse to load it.

Notes

  • Configuration override mechanism: A Profile patch replaces the plugin’s entire config, rather than performing a deep merge. If you need to modify only part of the configuration, you must explicitly write the other fields to preserve their default values.
  • Runtime mode differences: In Standard, PTC, and Creator modes, this plugin runs before the isolated engine and achieves 62.5% compression. Minimal mode does not use a preset compression group and uses the root engine directly.
  • Spill subsystem: The plugin uses DSH’s spill subsystem (dsh-spill-local and dsh-spill-policy) and acts as the retrieval authority for persistent archives.
  • License: Complies with the MIT License.

Conclusion

This tool helps developers effectively manage DSH context expansion through compression strategies and recoverable mechanisms. For more details, refer to the plugin directory or the GitHub repository.