dsh-cwl

Readme

# dsh-cwl

**CWL — Context Window Lifecycle** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):
structured context eviction for long-horizon agents.

> Paradigm: [*Beyond Compaction: Structured Context Eviction for Long-Horizon Agents*](https://arxiv.org/abs/2606.11213) (arXiv:2606.11213, Kiz8)

**English** | [简体中文](./README.zh-CN.md)

## 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

1. **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.
2. **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).
3. **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

```bash
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:

```yaml
- 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.

```bash
# 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 |

```bash
# 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"):

```bash
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

```bash
node check.js          # pure-function unit checks (episode inference, eviction policy, strip, pairing)
```

Live capability benchmarks (helmsman platform): **[BENCHMARKS.md](./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