dsh-compaction-micro

Readme

# dsh-compaction-micro

Standalone **micro-clear tier** for DeepSeek Harness compaction. It clears whitelisted, re-runnable tool results to placeholders at its own `microThresholdRatio` — below the summarize threshold — so the expensive model-backed summary runs less often. It is an observer: it never mutates the model request, makes no model call, and every rewrite is a single-node `tool/result` content replacement preceded by a `compaction/prune` shadow-price event, so the durable log stays the reconstructable source of truth.

Snip (trimming) and full (summarization) stay owned by the official `dsh-compaction-tool-result-pruner` and `dsh-compaction-basic`.

## Composition

Mount this bundle **before** `dsh-compaction-basic`. Its `agent/pre-step` and `agent/request-error` listeners are registered with `prepend: true`, so they run first regardless of mount order:

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

1. **`agent/pre-step`** (prepend): measure pressure; when `totalTokens >= floor((contextWindow - reservedTokens) × microThresholdRatio)`, clear whitelisted tool results oldest-first, retaining the newest `retainRecent` visible. The official backend then re-measures the smaller surface and skips summarization when the clear already relieved enough pressure.
2. **`agent/request-error`** (prepend): on a confirmed context overflow, clear whitelisted results first, then delegate to the official prune + summarize + retry.

## Configuration

| Field | Default | Meaning |
|---|---|---|
| `clearableTools` | `[]` | Tool names whose results the micro tier may clear. Empty disables the tier. Only list read-only, re-runnable tools — the service does not verify that property. |
| `retainRecent` | `3` | Newest clearable results always retained visible. |
| `microThresholdRatio` | `0.85` | Clear at this fraction of the effective window. Must be in `(0, 1]`. |
| `reservedTokens` | `0` | Tokens subtracted from the routed context window before scaling the threshold. |
| `auto` | `true` | Install the automatic listeners; `false` exposes only `ctx.microCompaction.clearSession()`. |

The whitelist is operator-owned and is the safety gate: `read`/`glob`/`grep` and read-only web tools are the intended members; `write`, `edit`, shell, subprocess, and workflow tools must stay out.

## Development

Build against a local DeepSeek Harness checkout by junctioning its workspace packages into `node_modules/@deepseek-ai` (see the checkout's `packages/*/*` and `vendor/*`), then:

```sh
npm run typecheck     # tsc -p tsconfig.json --noEmit
node --import tsx --test tests/micro.test.ts
```

Runtime smoke (from the DSH checkout):

```sh
dsh plugin --profile headless add link:<this-dir>
DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 DEEPSEEK_API_KEY=mock-key \
  dsh --profile headless "run the pwsh tool once and report"
```

## License

MIT