dsh-optimize

Readme

# dsh-optimize

Long-session resource governor for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

A conversation that keeps growing gets expensive long before anything
compacts it: every step re-sends the retained history, the session log grows
without bound, and the web UI has more history to draw. `dsh-optimize`
measures that growth and reports it, so a heavy session is a visible fact
rather than a surprise.

## What it does

- Measures what every outgoing request actually carries (message count,
  characters, estimated token range) on each `agent/pre-step`.
- Reads the harness's own `contextPressure` projection on session events — the
  authoritative token figure, and O(1) — so the estimate above is never the
  only number kept.
- Keeps a per-session record — requests, events, last and maximum request
  weight, projected tokens, compaction count — in
  `$DSH_HOME/storages/dsh-optimize/state.json`.
- Logs a warning the first time a session crosses `warnTokens`, and again at
  `criticalTokens`, with the measured range.
- Optionally (off by default) runs the session's **own** compaction engine
  once the measured weight passes `compactAtTokens`, through the sanctioned
  `ctx.agentPresets.serviceFor(agent, 'compaction')` handle. The plugin decides
  *when*; the harness engine keeps deciding *what* to summarise.
- Provides the `optimize` host service (`snapshot(id)`, `list()`, `flush()`).

It does **not** change the system prompt, the tool schemas, or the request
prefix, does not write session events, and does not touch the session log.

## Install

```sh
dsh plugin --profile <profile> add dsh-optimize
```

Or from a checkout:

```sh
dsh plugin --profile <profile> add /path/to/dsh-optimize
```

## Configure

The bundle patch ships the defaults; override them in your profile's patch
layer (`~/.dsh/profiles/<profile>/cordis.patch.yml`):

```yaml
- id: dsh-optimize
  config:
    warnTokens: 120000
    criticalTokens: 300000
    autoCompact: false
    compactAtTokens: 200000
    compactCooldownMs: 300000
    verbose: false
```

| Key | Default | Meaning |
| --- | --- | --- |
| `warnTokens` | `120000` | Estimated request weight that marks a session as heavy. |
| `criticalTokens` | `300000` | Estimated request weight that marks a session as critical. |
| `autoCompact` | `false` | Run the harness compaction engine over budget. |
| `compactAtTokens` | `200000` | Measured weight at which automatic compaction may run. |
| `compactCooldownMs` | `300000` | Minimum delay between two automatic compactions. |
| `verbose` | `false` | Log every measured request, not only threshold crossings. |

The estimate is a range: Latin text is near four characters per token, CJK near
one and a half. The upper bound is the one compared against the thresholds, so
a mixed-language session errs towards reporting early. When the harness's
`contextPressure` projection is available, its number wins for the compaction
decision.

## Notes on automatic compaction

- It is **off by default**, because it changes what the model sees. The
  built-in engine already compacts when the routed model's window is nearly
  full (ratio `0.8` by default) or when the provider reports a context
  overflow; this option only makes it fire earlier, at your budget.
- The engine is mounted inside the agent preset's isolate realm, so the only
  sanctioned handle is `ctx.agentPresets.serviceFor(agent, 'compaction')`.
- Its thresholds are frozen at construction: nothing can retune the engine at
  runtime, and changing `thresholdRatio`/`retainRatio` means editing the preset
  row and re-mounting.
- Compaction needs an idle agent; a request made mid-turn is refused with
  `busy` and retried on a later check.

## In the browser

The chat view mounts one DOM row per visible node of the loaded history and
lays out every one of them; only the trajectory table virtualises. On a long
session that is thousands of live rows.

- **Lite rendering** (on by default, switchable): a stylesheet puts
  `content-visibility: auto` and `contain-intrinsic-size: auto 320px` on
  `[data-chat-anchor-key]`, so the browser skips layout and paint for rows
  outside the scrollport. React still reconciles them exactly as before, and
  the remembered row height keeps scroll anchors stable.
- **Composer chip**: shows the current state and how many rows are mounted;
  clicking it toggles lite rendering.
- **Settings row**: the same switch, under Settings → General.

The switch is persisted in `localStorage` under `dsh-optimize:lite`. Nothing
about the session is hidden or unloaded: every row stays mounted and reachable.

## Roadmap

- A context-pressure readout in the composer chip, read from the harness's own
  `contextPressure` projection.

## License

MIT.