- Главная
- Плагины
- Сеансы и сообщения
- smart-compaction
smart-compaction
joblessjoe/smart-compaction
Позволяет модели запускать сжатие в безопасный момент через compact_now (в том числе посреди хода). context_status показывает фактическое число использованных токенов относительно реального окна контекста сессии.
Установка
dsh plugin --profile web add github:joblessjoe/smart-compactionREADME
A DeepSeek Harness (dsh) plugin that lets the model decide when to compact its own context, instead of being cut off mid-task by a blind token threshold.
compact_now: compacts at a point the model knows is safe, e.g. right after finishing a todo. Works mid-turn.context_status: real token usage against the session's actual context window, so the model stops guessing.- Automatic safe-point compaction: local models rarely call a tool like this on their own, so the plugin also compacts by itself the moment a todo item is marked done and the context is over 60% full. No model decision needed.
- Hides old tool output, keeps it recallable: big tool results more than 4 steps old shrink to a short preview, in batches.
recall_outputbrings any of them back word for word. No model call. - Hides outdated file reads: once a file is read again or rewritten, older copies are hidden, so the model doesn't work from code that is no longer there.
- Smaller reply reserve and file reads: caps the reply reserve at 16k tokens (dsh's DeepSeek adapter defaults to 256k) and one
readat 20,000 characters, with anoffsethint to read on. - Fixes the early trigger: dsh's own compaction fires at ~33-45% on 128k local models. The plugin shrinks its reserve so it fires near 80% again.
- No core changes: built only on dsh's public compaction APIs.
npx @deepseek-ai/dsh plugin --profile web add smart-compaction
The web profile reloads live, so there's nothing to restart. Details and edge cases under Install.
Why
dsh's built-in compaction is purely reactive: an automatic trigger fires between agent steps whenever token pressure crosses a fixed threshold, with no idea whether that moment is a good one to interrupt. It can land between two dependent steps — e.g. right after reading a file and right before editing it based on what was just read — and the resulting summary loses exactly the context the very next step needed.
This plugin doesn't change how compaction works, only who decides when. It hands the model a tool it can call proactively, on its own judgment, instead of leaving that decision entirely to a blind token counter.
What it does
Two tools, both no-argument.
compact_now
- Selects the largest currently-compactable span of conversation history — the same
tool-call-pairing-safe boundary logic dsh's own compaction already guarantees, reimplemented
here against dsh's public APIs only (no dsh core changes, no dependency on
compaction-basic's internals). - Writes nothing to the chat history: it calls
compactRegion()directly and reports through the tool result (Compacted N history items (~T tokens).). An earlier version posted a "Compacting now" notice first, butcompact_nowruns inside its own tool call, so the notice landed between the assistanttool_callsmessage and itstoolresult. Strict providers then rejected every later request withMessages with role 'tool' must be a response to a preceding message with 'tool_calls'. (Fix by @Kita-Ikuyo, PR #1.) - Calls dsh's own
ctx.compaction.compactRegion()to actually do the compaction — the same summarizer, the same durablecompaction/start/compaction/endlog events, the same guarantees as any other compaction in the session. - No-ops harmlessly (
"Not enough compactable history yet.") if there isn't enough history yet — safe for the model to call speculatively.
context_status
- Read-only — never modifies the session, safe to call anytime.
- Reports current token usage and the model's actual context-window size for this session,
e.g.
"~42,300 / 77,824 tokens used (54.3%)." - Reads dsh's own
contextPressuresession projection (registered by@deepseek-ai/dsh-token-meter, mounted wherevercompaction-basicis) via the publicctx.sessionProjections.stateOf()API — the same numbers the web UI's own context meter reads. Nothing is hardcoded: the context-window figure comes from whatever model this session is actually routed to, so it's correct unchanged across different models, profiles, and context-window sizes. - Exists because, without it, the model has zero visibility into its own context usage — the
only prior signal was a vague "if the conversation feels long" in
compact_now's own description.
Automatic safe-point compaction
-
Watches
todo_write. When an item flips tocompleted, that's a finished step: a safe place to cut. -
If usage is past
safePointRatio(default 0.6) at that moment, it first hides stale tool output. Only if that is not enough does the next step start on compacted history. SamecompactRegion()path ascompact_now. -
Compaction keeps the newest ~16% of the window verbatim (the engine's own
retainRatio), so the model doesn't have to re-read what it was just working on. -
dsh's own 80% trigger stays as the backstop; this just gets there first, at a clean boundary.
-
A failure here never breaks the turn. It logs a warning and the backstop takes over.
-
Tune or turn it off in your profile's
cordis.patch.yml:- id: tool-compact-now config: safePointRatio: 0.6 # or false to disable
Hiding stale tool output (idea from @maskpoint/dsh, and JetBrains'
observation-masking study: tool output is most of an agent's
context, and hiding old output works about as well as a summary at half the cost)
- A tool result is stale once 4 newer model steps exist and it has 2,000+ characters.
- Stale results become their first 300 characters plus a marker with an id.
- Runs in one batch once stale output adds up to 10% of the window, not every step. Each rewrite of old history makes a local model re-read the prompt from there.
- Uses dsh's own prune protocol (the one
tool-result-pruneruses), so the token meter stays exact and the original stays in the session log.
Outdated file reads
- A
readresult is outdated once a later read covers the same lines, or a laterwritereplaced the file. It becomes a one-line marker naming the file and lines; the newer copy stays. - Hidden in the same batch as stale output (same cache-friendly rule).
Reply reserve (maxOutputTokens, default 16,384)
- Every request keeps room free for the model's reply, and dsh's compaction trigger subtracts that same room. dsh's DeepSeek adapter reserves 256,000 by default. The plugin caps it per request and never raises a lower value you already set.
Read cap (readMaxChars, default 20,000)
- dsh's
readreturns up to 51,200 bytes (~13k tokens). The plugin cuts longer results at a line boundary and ends them withUse offset=N to continue., so nothing is lost: the file is on disk.
System prompt (prompt, nothing cut by default)
- Logs each prompt section's and context's size once, so you can see what costs room.
dropSections,sections(replacement text),maxSectionCharsandmaxContextChars(e.g. AGENTS.md) trim them. A cut always says what was cut.- Tool schemas belong to dsh and can't be edited by a plugin. Remove whole tools in the web preset editor instead.
Not handled: file contents inside old write/edit calls. Hiding those means rewriting the
model's own messages, which dsh guards closely. Not done without testing on a real dsh.
recall_output (idea from dsh-compaction-vcc's recall)
- Takes the id from a marker and returns the full original text, capped at 60,000 characters.
Early-trigger fix (idea from dsh-compaction-policy / dsh-compaction-threshold)
dsh's compaction-basic triggers at floor(min(W × 0.8, W − O − headroomTokens)), with
headroomTokens = 65,536. On a 128k local model the second term wins, so it fires at ~33-45% and
then again every few steps. Its summary cap (maxTokens) is the same 65,536.
The plugin lowers both to summaryMaxTokens (default 16,384) on the live engine before each step,
so the trigger is back near 80% and the summary call still fits in the window. Values you set lower
yourself are kept. If you turn this off, the plugin logs a one-time warning with a suggested value
instead.
How it works
Two entry points exist on dsh's compaction service: compactNow() (what the human /compact
command uses — requires an idle agent, throws busy otherwise) and compactRegion() (what
dsh's own automatic between-step trigger uses — works fine mid-turn). A tool's execute()
always runs mid-turn — that's what calling a tool means — so compact_now is built on
compactRegion(), not compactNow().
Install
Into your dsh web profile (web below is the profile name; use whichever profile backs your
session). From a source checkout, use pnpm dsh instead of npx @deepseek-ai/dsh:
npx @deepseek-ai/dsh plugin --profile web add smart-compaction
This installs the package and adds it to dsh.profile.bundles for you. (No local dsh binary?
Run the equivalent by hand from the profile directory, e.g. ~/.dsh/profiles/web/: pnpm add smart-compaction, then add "smart-compaction" to that package.json's dsh.profile.bundles
array yourself.)
No build step, no restart: the shipped web profile reloads live, and the plugin shows up under
Plugins right away. Profiles without live reload (tui, headless, …) pick it up on their next
start.
Uninstall: npx @deepseek-ai/dsh plugin --profile web remove smart-compaction.
Requirements and preset-isolated profiles (read this if compact_now says no compaction service is configured)
compact_now needs a compaction service for the calling agent. Simple profiles mount one on
the host plane next to this plugin, and the plugin uses it directly. @deepseek-ai/dsh-web-app
profiles (the shipped web one) disable that host row; each preset (Standard, PTC, …) mounts its
own private compaction inside an isolated group instead. For those, the plugin asks the preset
registry for the calling agent's instance (agentPresets.serviceFor(agent, 'compaction'), dsh
0.2.0-rc.2+). Nothing to mount or edit by hand.
If compact_now still errors with "no compaction service is configured for this agent", the
agent's preset has no compaction-basic at all — add one (see
docs/subsystems/compaction.md
in the harness repo).
context_status requires @deepseek-ai/dsh-token-meter mounted (it registers the
contextPressure projection this tool reads). Unlike compaction-basic, the token meter is
deliberately kept on the host plane even on preset-isolated profiles (it owns a process-wide,
per-session projection table, not something that should come and go with which preset is mounted),
so the ordinary host-plane install always sees it — no preset patching needed for this one. If it
isn't mounted at all, the tool still installs cleanly and just reports available: false instead of
erroring.
Tell the model when to use it
This is baked into both tools' own descriptions, so it works out of the box with no setup: each
tool's description tells the model to check context_status right after finishing a
self-contained step (e.g. right after todo_write marks an item completed) and to follow up
with compact_now once usage climbs past roughly 70-90%. Since both descriptions are sent to the
model on every request automatically, no AGENTS.md edit is required for this behavior — unlike
an early version of this plugin, which relied entirely on a hand-written AGENTS.md rule and
(measured directly against real session logs) got essentially no organic use as a result: the
description alone wasn't a strong enough signal.
That said, standing instructions carry more weight than a tool description competing against
everything else in a long tool catalog. If you want to reinforce it further, copy this
into your AGENTS.md (or whatever your profile injects as standing instructions):
After marking a todo item
completed(never while one isin_progress), callcontext_status. Don't just compare the number to a fixed threshold — that's still reactive, and a step that turns out bigger than expected can blow past a comfortable-looking percentage mid-step. Instead, weigh what's left against what the next step will actually cost (a big file read, a long diff, a subagent dispatch); if it's not clearly going to fit with room to spare, callcompact_nownow, even while usage still looks moderate. Compacting a little early costs nothing; running out mid-step loses exactly the context that step needed. As a hard backstop, usage past roughly 70-80% of the context window is reason enough to compact regardless. Both tools are safe to call speculatively —context_statusis read-only, andcompact_nowno-ops if there isn't enough history to compact yet.
Tying this to todo-completion matters: it's a real, already-tracked signal for "I just finished a
self-contained unit of work," instead of asking the model to estimate its own remaining work or
guess whether a conversation "feels long," both of which it's generally bad at. context_status
replaces that guess with the real number.
The snippet deliberately does not say "compact once usage crosses 70-80%" as the primary rule — a threshold check alone is still reactive: a step that turns out bigger than expected (a large file, a long diff, a subagent dispatch) can blow straight past a comfortable-looking percentage during that step, which is exactly the mid-step interruption this plugin exists to avoid. The percentage is kept only as a hard backstop; the primary check is comparing remaining headroom against the size of the step about to start, and compacting early — before that step, not during or after it — whenever the fit looks tight.
Building from source
Requires Node 22+. Plain JS, no build step — git clone, pnpm install, done.
git clone https://github.com/JoblessJoe/smart-compaction.git
cd smart-compaction
pnpm install
node test.js
test.js is a pure unit-test check of the range-selection logic (select-range.js) and the
context-usage summary logic (context-status.js) — no live dsh/Ollama session required.
Configuration
All optional, in your profile's cordis.patch.yml:
- id: tool-compact-now
config:
safePointRatio: 0.6 # compact after a finished todo past this; false = off
summaryMaxTokens: 16384 # engine headroom + summary cap; false = leave the engine alone
mask: # false = never hide tool output
afterSteps: 4 # stale after this many newer steps
minChars: 2000 # smaller results are left alone
previewChars: 300 # preview kept in the mask
batchRatio: 0.1 # hide in one batch once stale output is this share of the window
dedupeReads: true # also hide outdated file reads
maxOutputTokens: 16384 # reply reserve per request; false = leave as is
readMaxChars: 20000 # cap one read result; false = dsh's own 51,200 bytes
prompt: # nothing is cut unless set
report: true # log section/context sizes once
dropSections: [] # section names to remove
maxContextChars: 8000 # e.g. cap AGENTS.md
Status
compact_now verified end-to-end against a real dsh session, including:
- Basic call: the tool loads, the model calls it, it selects a valid boundary-safe range, and it
drives
compactRegion()mid-turn without ever hitting thebusyfailure this design exists to avoid. - A real tool-call/tool-result pair (
todo_write, markedin_progressthencompleted) sitting in the compacted range — stays correctly paired, nothing split. - Three
compact_nowcalls in a row in one session (one accidental, caught by dsh's own duplicate-call guard mid-task) — each completed cleanly, no crash, nobusy, no corrupted state from operating on a surface that already contains an earlier compaction's checkpoint message.
Troubleshooting: if the tool returns an error like summarization produced no text summary content, that's not this plugin — compact_now selected a valid range and handed it to dsh's own
summarizer, which returned nothing. Observed specifically when the compacted range contains only
injected boilerplate (e.g. standing instructions) with no real assistant-generated text yet —
succeeded reliably once genuine conversation content was in the range. If it happens on ranges with
real content too, check whether your model's "thinking" level is an actually-enforced token budget
or just an instruction (e.g. Ollama's think: low is unenforced — a model can still spend its
entire output budget on hidden reasoning and return no visible summary text). Either way, this is a
model/summarizer-side issue, not something compact_now itself controls.
License
MIT
中文简介 · DeepSeek Harness (dsh) 插件:让模型自己决定何时压缩上下文,而不是在任务中途被固定的 token 阈值打断。提供
compact_now(在安全时机压缩,回合中途也可用)和context_status(对照会话实际的上下文窗口显示真实 token 用量);某个待办事项完成且上下文已用过半时,也会自动压缩。无需配置,不改动 dsh 核心。
安装:npx @deepseek-ai/dsh plugin --profile web add smart-compaction(web 配置实时加载,无需重启)
Похожие плагины
billion-context
ranxianglei/billion-context
dsh-web-ui (dsh-chat-recovery)
zhu1090093659/dsh-web-ui
dsh-synapse
liangmianya/dsh-synapse
dsh-archive-manager
michengai/dsh-archive-manager