dsh-cwl
CWL — Context Window Lifecycle for DeepSeek Harness:
structured context eviction for long-horizon agents.
Paradigm: Beyond Compaction: Structured Context Eviction for Long-Horizon Agents (arXiv:2606.11213, Kiz8)
English | 简体中文
Why not summarization compaction?
Compaction (the standard response to context pressure) summarizes history with an LLM.
Four structural problems (per the CWL paper):
- Unpredictable lossiness — the summarizer decides what matters, not the task.
- Structural destruction — causal chains (tool call → output → decision → action) collapse into prose.
- Blocking cost — a full LLM call fires mid-task, under token pressure.
- Compression-induced hallucination — summarization under length pressure is a known failure mode.
CWL treats the transcript as a structured record of work and evicts deterministically:
the agent's trajectory is inferred into a typed episode graph (exploration expl / action act,
with dependency edges), and when context pressure exceeds budget, a zero-LLM, deterministic policy
strips content in graduated levels — exploration episodes first (pure context, safest), then action
episodes whose effects are already persisted. User messages are never evicted.
How it works
- Episode inference (automatic, no agent annotation needed): consecutive same-type tool
batches merge into semantic episodes (
expl for pure read/search — including read-only
bash like grep/cat — act for anything with side effects: edit/write/write-style bash).
Each user message closes the current episode (a turn boundary), and episodes are capped at
a batch limit, so even a single-request long autonomous run (dozens of tool calls) splits
into bounded, evictable segments instead of collapsing into one giant episode. An act
that touches files an earlier expl read gets a dependency edge.
- Pressure metering: real context pressure = input + cacheRead + output + reasoning tokens
(accumulated from
assistant/message usage events — tokenMeter.measure().totalTokens omits
cacheRead, which dominates long sessions).
- Graduated eviction on the
agent/pre-step waterfall (before every LLM call), from
fine to coarse:
- content stubbing (fine): large tool-result contents in
expl episodes are rewritten
to a short stub first ([cwl-stub: …]) — structure kept, tokens cut, tool pairing intact
- whole-episode eviction (coarse):
expl episodes first (pure context, one-line
"explored: …" marker), then completed act episodes; executed as positional blocks
in the surface (positions are the invariant that survives replaces — an eviction never
splits a tool-call/result pair into orphans)
- never touch the newest tail (preserve-recent) or user messages
- evicted ranges are replaced with a lightweight marker via the official surface-replace
seam (original events stay in the log;
cwl_recall can restore file paths)
Install
dsh plugin --profile <name> add dsh-cwl # from npm
dsh plugin --profile <name> add github:kalifun/dsh-cwl # or from GitHub
Or vendor the directory and add to your composition:
- id: dsh-cwl
name: ./dsh-cwl/index.js
Usage
No configuration needed. It stays completely inert while context is under budget
(default 80% of the model's context window), and starts evicting only when pressure
exceeds budget.
# Optional: override the budget (tokens) — for testing pressure behavior
DSH_CWL_BUDGET=30000 dsh web
Eviction policy (deterministic cache-replay validation: eviction −24% cacheRead,
strategy-independent; batch best mean −24.7%, consistent across 7 sessions → defaults
below; override via env):
| Env var | Default | Values | Effect |
|---|
DSH_CWL_EVICT_ORDER | tail | tail / oldest | oldest evicts oldest episodes first |
DSH_CWL_EVICT_BATCH | on | 0 / false / off to disable | merge adjacent episodes into one surface replace (fewer cache breaks) |
DSH_CWL_EVICT_TAIL_WINDOW | 0 | N | only evict episodes whose end falls within the last N surface nodes |
DSH_CWL_STRIP | on | 0 to disable | fine-grained level: stub large tool-result content in expl episodes before whole-episode eviction (structure preserved) |
DSH_CWL_STRIP_THRESHOLD | 1500 | chars | minimum result text length to be stubbed |
# back to the conservative config (oldest, per-episode replaces)
DSH_CWL_EVICT_ORDER=oldest DSH_CWL_EVICT_BATCH=0 dsh web
Session analysis (per-round token breakdown + "cacheRead of the round after an eviction"):
node tools/analyze-session.mjs <session.jsonl>
Agent-facing tools:
| Tool | Purpose |
|---|
cwl_recall | list file paths touched by evicted episodes, to re-read on demand |
Observability:
| Endpoint | Purpose |
|---|
GET /api/cwl/evictions | eviction log (session → episodes evicted) |
POST /api/cwl/force | debug: force one eviction on a session |
Verification
node check.js # pure-function unit checks (episode inference, eviction policy, strip, pairing)
Live capability benchmarks (helmsman platform): BENCHMARKS.md —
the fixed test plan (scenario A: 12-round long conversation; scenario B: single-request
long autonomous task ×3) with per-version data rows, refreshed after every behavioral change.
Offline regression tools (run on your own local sessions — no data leaves your machine):
tools/cache-replay.mjs (deterministic cacheRead), tools/replay-real.mjs --apply (engine
apply-layer with real surface fold + tool-pairing assertion), tools/eval-episodes.mjs.
License
MIT
