dsh-context-offload
Context offloading for DeepSeek Harness (dsh).
A coding agent re-sends its whole history on every step, and most of that history is
tool output it already used: the file it read, the command it ran, the diff it
applied. This plugin releases that content from the model-visible history once
it is no longer needed, replacing each consumed tool call and its results with a
one-line stub. Every original stays in the session log, so nothing is lost —
only the model's view shrinks.
Install
dsh plugin --profile web add dsh-context-offload
Restart dsh web. The plugin mounts into the profile composition and covers every
agent in that profile.
To switch it off without uninstalling, add to the profile's own cordis.patch.yml:
- id: context-offload
disabled: true
What the model sees
A tool unit — the assistant message that issued the calls plus every result
answering them — is shadowed by a single user/message stub:
[tool context offloaded — 2 tool call(s) removed from model context; 39,045 characters released]
- bash(command=cd /Users/me/proj && ls -la && for d in */; do echo …)
- read(path=src/harness/loop.ts)
The original arguments and results remain in the session log. Re-read a file or re-run a command if you need the content again.
Two paths produce that stub:
- Between steps — a policy on
agent/pre-step releases complete tool units
once more than retainUnits newer ones exist, and the accumulated backlog
reaches flushChars. It flushes at most once per flushEverySteps, because
every replacement moves the first divergence point of the request prefix and
flushing on every step would defeat the provider's KV cache on every step.
- On request — the
offload_context tool lets the model unload calls it has
finished with. The request is recorded during the tool call and applied at the
next step boundary, which is the sanctioned surface-mutation point; a tool body
runs mid-step and must not rewrite the surface.
Units whose calls are not all answered — an in-flight or interrupted step — are
never touched, and the system prompt at surface node 0 is never inside a range.
Configuration
All fields are optional.
| Field | Default | Meaning |
|---|
enabled | true | Set false to keep only the model-facing tool. |
retainUnits | 8 | Most recent complete tool units kept verbatim. Counted in units, not steps — step restarts at 1 for every turn, so a step delta across a turn boundary is meaningless. |
minUnitChars | 4000 | A unit smaller than this many text characters is not worth a replacement. |
flushChars | 20000 | Do not break the request prefix for less than this much releasable backlog. |
flushEverySteps | 10 | At most one automatic flush per this many steps. |
maxUnitsPerFlush | 40 | Upper bound on replacements appended in a single flush. |
Where it sits in the composition
This package ships a host-plane bundle: dsh.bundle.patch mounts one row into
the profile composition, which is the only channel a published package has. A
preset-plane mount is possible but must be made by hand — an installed package
cannot contribute an agent-preset root (package.json.dsh carries no preset
field, and a patch cannot compute a path relative to its own package). To scope
this to one preset instead of the whole profile, do not enable the bundle row:
install the package so node_modules can resolve it, and add the row to your own
preset copy:
- id: context-offload
name: dsh-context-offload
Enable exactly one of the two, never both.
compaction-basic remains authoritative for context pressure; this plugin is a
complement. Both append logged surface replacements and both listen on
agent/pre-step, and ordering between them does not matter because each only ever
shadows complete tool units or its own balanced range.
Why you cannot see it in the transcript
Surface replacements are model-only. The human transcript is rendered from
append-origin events on purpose, so a landed replacement never erases conversation
you already read. To observe the effect, watch the context-occupancy ring beside
the composer: it stops climbing and enters a sawtooth, and its click-open panel
shows the conversation segment flattening.
License
MIT
