跳过主要内容
J

smart-compaction

joblessjoe/smart-compaction

让模型自己挑安全时机触发压缩:提供 compact_now 工具(回合进行中也能用),另有 context_status 工具,按会话真实的上下文窗口报告 token 占用。

安装

dsh plugin --profile web add github:joblessjoe/smart-compaction

README

smart-compaction: dsh auto-compacts mid-task; with smart-compaction the model compacts between tasks

npm version npm downloads MIT license project page on joblessjoe.com listed on awesome-dsh-plugin

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_output brings 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 read at 20,000 characters, with an offset hint 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, but compact_now runs inside its own tool call, so the notice landed between the assistant tool_calls message and its tool result. Strict providers then rejected every later request with Messages 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 durable compaction/start/compaction/end log 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 contextPressure session projection (registered by @deepseek-ai/dsh-token-meter, mounted wherever compaction-basic is) via the public ctx.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 to completed, 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. Same compactRegion() path as compact_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-pruner uses), so the token meter stays exact and the original stays in the session log.

Outdated file reads

  • A read result is outdated once a later read covers the same lines, or a later write replaced 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 read returns up to 51,200 bytes (~13k tokens). The plugin cuts longer results at a line boundary and ends them with Use 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), maxSectionChars and maxContextChars (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 is in_progress), call context_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, call compact_now now, 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_status is read-only, and compact_now no-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 the busy failure this design exists to avoid.
  • A real tool-call/tool-result pair (todo_write, marked in_progress then completed) sitting in the compacted range — stays correctly paired, nothing split.
  • Three compact_now calls in a row in one session (one accidental, caught by dsh's own duplicate-call guard mid-task) — each completed cleanly, no crash, no busy, 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 配置实时加载,无需重启)

相关插件