billion-context-relief
Agent-requested context relief for DSH (DeepSeek Harness). A companion plugin to billion-context-dsh (ACP).
ACP lets an agent compress a range of its context into a summary the agent writes. Sometimes a summary is the wrong tool:
- Bulky but possibly needed again verbatim (a long log, a fetched page, a file dump). Move it out of the window into a file and keep a pointer:
context_export.
- No further value at all (a dead-end search, a superseded snapshot, a stale reminder). Drop it, with no summary and no file:
context_delete.
The plugin adds those two moves, plus a way to find what is worth moving (context_large_blocks) and a way to clean up the exported files (context_exports).
Every change is an explicit agent call. Nothing is compressed, exported, deleted or cleaned up automatically. The only thing that runs on its own is an advisor notice, and it only informs.
Contents
Requirements and compatibility
Package: billion-context-relief on npm. Published files: lib/, cordis.patch.yml, README.md, CHANGELOG.md, LICENSE (about 19 kB packed, no runtime dependencies).
| Component | Version | Status |
|---|
| DSH | 0.2.0-rc.2 | ✅ compatible. Live-tested in a real DSH session (export, delete, refusals, export cleanup). |
| DSH | 0.1.x | ❌ not supported. The 0.2 compaction seam and session surface are required. |
| billion-context-dsh (ACP) | github:Tyan66666/billion-context-dsh#2026-09-30_dsh-0.2-seam-port (reports 0.2.26) | ✅ tested |
| billion-context-dsh (ACP) | npm billion-context-dsh@0.2.26 | ⚠️ expected to work (same version and exports), not tested |
| billion-context-dsh (ACP) | the DSH 0.1 line | ❌ not supported |
| Node.js | >= 20 | required |
Runtime dependencies: none. billion-context-dsh is a peer dependency: it must already be installed in the same DSH profile and active as the compaction engine.
The declared DSH compatibility is in package.json → dsh.compatibility.dshReleases.
ACP dependency
This plugin does not implement its own compaction. Every replacement is made through ACP's own compress path, so ACP must be:
- installed in the profile (
billion-context-dsh in the profile's package.json), and
- the active compaction engine, i.e. listed in
dsh.profile.bundles. ACP's bundle replaces compaction-basic.
What it uses from ACP (all public exports of billion-context-dsh):
| Export | Used for |
|---|
AcpCompactionEngine | identifying the live engine (ctx.compaction) and reading its env and context window |
makeTools(env) → compress | performing each replacement through ACP's compress handler |
resolveSurfaceRange | resolving a requested span to ACP's live, tool-pair-balanced range |
shadowedSeqsOf | the exact messages a range will hide |
AlreadyCompressedRangeError | refusing ranges that are already inside an ACP block |
How ACP is located:
- First as a normal import (
billion-context-dsh resolvable from this package).
- When this plugin is linked from a folder outside the profile (
link: install), from ~/.dsh/profiles/*/node_modules/billion-context-dsh. Only a copy whose AcpCompactionEngine is the class of the live engine is accepted, so a stale or second copy is never used.
Without ACP (not installed, or another compaction engine active), every tool answers that ACP is required and changes nothing. The advisor stays silent.
ACP's global configuration is never modified. See How replacements work for the two per-call differences.
Install
Install ACP first, if the profile doesn't have it yet:
dsh plugin --profile web add "billion-context-dsh@github:Tyan66666/billion-context-dsh#2026-09-30_dsh-0.2-seam-port"
Then install this plugin from npm (recommended):
dsh plugin --profile web add billion-context-relief
Pin a version with billion-context-relief@0.1.2. To upgrade later:
dsh plugin --profile web update billion-context-relief
or from GitHub (pinned to a release tag):
dsh plugin --profile web add "billion-context-relief@github:markelayan/billion-context-relief#v0.1.2"
or as a local link, for development:
dsh plugin --profile web add "billion-context-relief@link:/path/to/billion-context-relief"
dsh plugin add puts the package in the profile's package.json and in dsh.profile.bundles, and the running DSH picks it up without a restart. The plugin's tools appear in sessions opened after the install: a session's tool list is fixed when the session is composed, so reopen sessions that should use it.
Check that it loaded: the DSH log (~/.dsh/dsh-web.log for dsh web) shows
[billion-context-relief] ready — tools: context_large_blocks, context_export, context_delete, context_exports · advisor=true · exports in <tmpdir>/billion-context-relief
Uninstall:
dsh plugin --profile web remove billion-context-relief
Blocks already created stay in the sessions as ordinary ACP blocks. Export files stay on disk until deleted; see Exports.
Tools
Range boundaries are surface seqs (integers) or ACP mNNNNN refs, as shown by context_large_blocks and acp_status. Ranges are inclusive.
context_large_blocks
Lists oversized items outside the protected zone. Read-only.
| Parameter | Type | Description |
|---|
largeMessageTokens | integer | Override the single-message threshold for this call |
largeTurnTokens | integer | Override the per-turn threshold for this call |
largeBlockTokens | integer | Override the ACP summary-block threshold for this call |
limit | integer 1–50 | Max items (default 20) |
Example output:
Thresholds: message ≥4.0K · turn ≥12.0K · ACP block ≥3.0K tokens.
· seqs 278–394 · turn 6 (38 msgs) · ~50.1K tok · 6 turns ago
· seq 308 · tool web_fetch · ~12.5K tok · 6 turns ago
· seq 355 · tool web_fetch · ~11.4K tok · 6 turns ago
usage 45% · oversized messages/blocks ~40.8K tok
Turn entries overlap their messages — act on either, not both.
Labels show the kind of item (tool name, runtime-context snapshot, plugin:<name>, ACP summary block, …). They never show content.
context_export
Writes a range of completed context to a temp file without the model reading it, and replaces the range with a one-line pointer.
| Parameter | Type | Required | Description |
|---|
startSeq | seq or mNNNNN | ✅ | First message |
endSeq | seq or mNNNNN | ✅ | Last message |
name | string | | File-name hint, e.g. pytest-run-3 |
note | string | | One line kept in the pointer (max 120 chars) |
What stays in context:
[CONTEXT EXPORTED (temp file) → /…/billion-context-relief/<session>/2026-10-04_205824_pytest-run-3.md · 2 msgs · seqs 306–308 · ~12.5K tok · note: …]
The agent can read the file later with its normal file tools if it needs the content back.
context_delete
Replaces a range with a marker. No summary and no file.
| Parameter | Type | Required | Description |
|---|
startSeq | seq or mNNNNN | ✅ | First message |
endSeq | seq or mNNNNN | ✅ | Last message |
reason | string | ✅ | Why it is safe to drop; kept in the marker (max reasonMaxChars) |
confirm | boolean | above deleteConfirmTokens | Required for ranges over 8,000 tokens (default) |
What stays in context:
[DELETED REFERENCES · seqs 363–365 · 2 msgs · ~12.8K tok · reason: consumed docs fetch, findings in report]
context_exports
Manages this session's export files by name only: it never opens or prints a file's content.
| Parameter | Type | Required | Description |
|---|
action | "list" or "delete" | ✅ | |
names | string[] | for delete | File names from list |
all | boolean | | delete every export of this session |
list shows file name, size, seq span, message count, token estimate and note. Names are validated, so path escapes (../) are refused. Only the calling session's own exports are visible.
How replacements work
Each replacement goes through ACP's own compress path (makeTools(env) → compress → kernel.applyCompression → ACP state store → durable compaction transaction), with the pointer or marker as the "summary". The result is a normal ACP block:
acp_status lists it, search_context finds text inside it, and decompress can still read the originals from the session log;- DSH's usage meter credits the freed tokens (live test: 45% → 39% after one 12.5K export).
Range handling. Before ACP resolves a range, the plugin widens it so no tool call or result is cut in half: a range that starts on a tool result also takes in the assistant message that made the call, and a range that ends on a call takes in its result. ACP itself shrinks a range to a balanced remainder, which would otherwise silently leave the first result in context. The tool's answer always reports the actual span acted on.
Two per-call differences from a model compress:
compress.minCompressRange is 0 for these calls. ACP's 5,000-character floor would otherwise stop a single small row (such as one plugin reminder) from being removed.- The relief tool's own call and result are not hidden from the transcript (ACP hides its own
compress calls).
ACP's global configuration is never changed.
What it refuses
Nothing changes when a call is refused; the answer says why.
| Case | Answer |
|---|
| The current (open) turn | reach into the current (open) turn — only completed turns can be relieved |
| The kernel's protected zone (last 5 messages, last 5K tokens, most recent user message) | are in the protected zone … — pick older messages |
| A range already inside an ACP block | already inside an ACP block — nothing to relieve; decompress reads the originals |
context_delete without a reason | a reason is required |
context_delete over deleteConfirmTokens without confirm: true | asks for confirm:true or suggests context_export |
| The newest AGENTS.md / agent-instructions copy | rejected by ACP (DSH re-injects it immediately) |
| ACP not active | explains that ACP is required |
If ACP refuses a range after the export file was written, the file is removed again.
Advisor
A notice the agent receives in its conversation. It is inform-only: it never edits, exports or deletes anything.
It is sent when all of these hold:
- the session's context usage is at least
minUsagePct (default 40%);
- at least one oversized item exists outside the protected zone;
- the list of top items has changed since the last notice;
- at least
advisorCooldownSteps steps (default 8) have passed since the last notice.
[billion-context-relief: large context — act on it if no longer needed]
· seq 342 · tool bash · ~9.2K tok · 23 turns ago
· seq 118 · runtime-context snapshot · ~4.2K tok · 30 turns ago
usage 61% · oversized messages/blocks ~13.4K tok
Tools: context_export (keep a temp copy) · context_delete (drop, no copy). This notice can itself be removed with context_delete.
Older notices are never removed automatically. The agent can delete them like any other content. Set advisorEnabled: false to turn the notice off; the tools keep working.
Exports
- Location:
<os tmpdir>/billion-context-relief/<session-id>/, or <exportRoot>/<session-id>/ when configured. On macOS the tmpdir is under /var/folders/…/T/.
- Permissions: directory
0700, files 0600.
- Index: each session directory has an
index.json with metadata (span, count, tokens, note), so listing never opens an export.
- Format: Markdown, one section per message (
## seq N · <label>) with the original text, tool calls and tool results.
- Lifetime: nothing deletes exports automatically. They stay until the agent calls
context_exports with delete (by name, or all: true). delete all also removes the session directory. The operating system may purge old files in its temp directory on its own schedule; set exportRoot if exports must survive that.
Configuration
Defaults ship in this package's cordis.patch.yml. Override them with a same-id row in your profile's cordis.patch.yml (~/.dsh/profiles/<profile>/cordis.patch.yml):
- id: billion-context-relief
config:
largeMessageTokens: 4000 # single message
largeTurnTokens: 12000 # one completed turn
largeBlockTokens: 3000 # one ACP summary block
minUsagePct: 0.4 # advisor stays silent below this usage (0–1)
advisorEnabled: true # inform-only notice; never modifies context
advisorCooldownSteps: 8 # min steps between notices per session
maxItems: 5 # items per advisor notice
deleteConfirmTokens: 8000 # context_delete above this needs confirm:true
reasonMaxChars: 120 # max length of the delete reason in the marker
exportRoot: '' # '' → <os tmpdir>/billion-context-relief
Unknown keys are ignored. Values of the wrong type fall back to the default.
Safety and data notes
- Not undoable in the session. ACP's
decompress returns the original content for reading, but it does not un-compress the range. Treat context_delete as permanent for the session, and use context_export when unsure.
- Originals are not erased from disk. Both moves remove content from the model's view. The session log keeps the original events (that is what
decompress reads). This plugin never edits session logs.
- Exports hold raw conversation content, including anything sensitive a tool printed (keys in logs, personal data in fetched pages). Keep
exportRoot outside any repository or synced folder.
- No network access. The plugin makes no outbound requests and registers no HTTP routes.
- Scope. A tool call can only act on the calling session's own context and exports.
Upgrading and reloading
- Reloading the plugin from the DSH GUI, or restarting DSH, loads new code.
dsh plugin remove + add updates the profile, but a module already loaded in the running process may keep its old code until a reload.
- Sessions get new or changed tool schemas only when reopened.
- Blocks and markers created by earlier versions stay valid; they are ordinary ACP blocks.
See CHANGELOG.md.
Troubleshooting
| Symptom | Cause / fix |
|---|
| Tools answer that ACP is required | ACP is not installed in this profile, or not in dsh.profile.bundles, or another compaction engine is active |
| Tools missing in a session | The session was opened before the install. Reopen it. |
ready line missing from the log | Check that billion-context-relief is in the profile's package.json and dsh.profile.bundles (dsh plugin --profile web list) |
| Reported span differs from the requested one | Expected: the range was widened to whole tool call/result pairs, or narrowed to messages not already in an ACP block. The answer shows the actual span. |
| Export pointer points to a missing file | The export was deleted with context_exports, or the OS purged its temp directory. decompress still reads the originals. |
Development
npm test
Node's built-in test runner covers the helpers (test/core.test.mjs: scanning, protected zone, markers, export store, range widening) and the tools against a mocked DSH host and ACP module (test/host.test.mjs). There are no external dependencies.
Related plugins
This plugin replaces the old local dsh-ctxdel plugin, whose automatic deletion sweep is gone entirely.
License
MIT
