Introduction

In the development and operations of DeepSeek Harness (DSH), prolonged pressure on the context window is a common issue faced by long-running sessions. Traditional approaches often rely on LLM-based summarization and compaction, but this introduces four structural problems: unpredictable loss, structural destruction (causal chains collapsing into prose), blocking costs (triggering full LLM calls in the middle of a task), and compaction-induced hallucinations.

To address these issues, dsh-cwl provides an alternative: structured context eviction based on Context Window Lifecycle (CWL).

What Is This

dsh-cwl is a plugin for DeepSeek Harness, maintained by kalifun. It infers an agent’s trajectory as a typed episode graph (exploration expl / action act) and, when context pressure exceeds the budget, executes a zero-LLM, deterministic tiered eviction strategy.

Its core design philosophy is based on the paper Beyond Compaction: Structured Context Eviction for Long-Horizon Agents, aiming to avoid the losses introduced by summarization while preserving the structural integrity of the context.

Core Features

  1. Automatic episode inference: Without manual annotation, it automatically merges consecutive tool batches of the same type into semantic episodes. Exploratory operations are expl (e.g., grep/cat), while operations with side effects are act (e.g., edit/write). User messages close the current episode.
  2. Tiered eviction mechanism: When context pressure exceeds the budget, it first performs content truncation (content stubbing), and then evicts entire episodes. The eviction order prioritizes expl before act.
  3. Protection mechanism: User messages are never evicted, and eviction is applied as positional block replacement, preserving the pairing between tool calls and their results.
  4. Tooling and observability:
    • Provides the cwl_recall tool for reading the paths of evicted files on demand.
    • Provides the API endpoint /api/cwl/evictions to inspect eviction logs and /api/cwl/force to force-run an eviction.

Installation and Activation

Before installation, make sure DeepSeek Harness is installed and the Profile is configured.

dsh plugin --profile <name> add github:kalifun/dsh-cwl

The plugin requires the following environment:
* Node.js: ^22.19.0 || >=24.0.0
* Peer Dependencies: @deepseek-ai/cordis, @deepseek-ai/dsh-compaction, @deepseek-ai/dsh-token-meter

Typical Usage

Basic Run

By default, the plugin remains idle until context pressure exceeds 80% of the budget, and eviction starts only when the threshold is exceeded.

Configuration Adjustments

Adjust the eviction strategy and budget via environment variables:

# Set custom budget (tokens)
DSH_CWL_BUDGET=30000 dsh web

# Set eviction order to oldest (from old to new)
DSH_CWL_EVICT_ORDER=oldest DSH_CWL_EVICT_BATCH=0 dsh web

# Adjust stub granularity (default 1500 characters)
DSH_CWL_STRIP_THRESHOLD=1000 dsh web

Validation and Debugging

# Run validation checks
node check.js

# Run session analysis
node tools/analyze-session.mjs <session.l>

Applicable Scenarios and Considerations

dsh-cwl is suitable for scenarios that require handling long-span conversations and depend on context replay validation. Because the plugin runs with the permissions of the current dsh process, it is recommended to review the source code and license before installation.

Summary

dsh-cwl replaces traditional LLM summarization and compaction with structured eviction, addressing the lack of determinism and structural destruction in context management. Together with the cwl_recall tool and observability endpoints, developers can precisely control the lifecycle of the context.