agent-compact

English · 简体中文

Context compression for DeepSeek Harness: lets the agent autonomously call context_compact to compress a span of the conversation it chooses — the finished, no-longer-needed middle — and replace it with a checkpoint the agent writes itself.

Why

Compaction is normally a full-context sweep: the official engine only ever compresses from the start of the conversation, so the opening's task plan and direction are partially lost along with the compressed information. context_compact compresses only the span the agent selects — a finished step, a debugged log exchange, an off-track discussion — while the important opening and the recent context stay intact. Span compaction keeps information loss from compaction as small as possible — like human memory, the middle is not compressed indiscriminately: what can be summarized is consolidated into a checkpoint, and important details stay word-for-word — the agent decides what is truly dead, and only that gets condensed.

Typical moments to use it:

• a task step is done — compress it, keep the remaining steps and the active instruction live;
• a bug hunt or a wrong research direction is over — compress that exchange into a short "what went wrong / root cause / fix" note;
• the opening requirements are stale — compress the start and restate the current intent.

What it does

• The agent picks the span via startAnchor / endAnchor (unique-prefix matching, CJK punctuation-width tolerant) and passes a required summary — the Markdown checkpoint it wrote itself.
• The raw span is archived to the spill store first (~/.dsh/spill/session-<hash>/<hex>-<seq>.txt, sequential naming, restart-safe); the path is echoed in the shadow message so the model can read the raw text back.
• The host engine runs the stock transaction — boundary validation, tool-pair balance, surface replacement — with no separate LLM summarizer request.

The tool call itself happens inside the agent's normal turn and is billed like any other turn; what is avoided is only the extra summarizer request the official engine would make for the same span.

Install

# from a published registry package
dsh plugin --profile web add @mimichunterz/agent-compact

# or from a local checkout
dsh plugin --profile web add ./agent-compact

dsh plugin forwards to pnpm in the profile directory and appends the bundle to dsh.profile.bundles (see the official publish guide). Restart the profile — every session then sees the context_compact tool.

The bundle's own cordis.patch.yml pins the spill archive root to ~/.dsh/spill (deployments can override it again through the profile's cordis.patch.yml).

Uninstall

dsh plugin --profile web remove @mimichunterz/agent-compact

dsh plugin remove forwards to pnpm remove in the profile directory: it uninstalls the package and reconciles the bundle out of dsh.profile.bundles. Restart the profile — every session then stops seeing the context_compact tool. The same package name works whether you installed from the registry or from a local checkout.

If the plugin was additionally mounted through a row in the profile's cordis.patch.yml (dev mode), remove that row too, otherwise the patch re-mounts it on the next boot.

Configuration

Pass through the inserted row in the profile's cordis.patch.yml or a bundle patch.

How it works

• Agent-written checkpoint: summary is mandatory, so the tool path always uses the checkpoint the agent wrote. patchEngine() (see src/optimizer.ts) wraps the engine's summarize(): when an _externalSummary is present (one-shot, keyed per session id), it returns that text directly; only when none is present does it forward to the stock implementation — a branch that serves the automatic compaction path and keeps official behavior intact.
• Anchor matching (src/normalize.ts): normText collapses whitespace and maps CJK full-width punctuation to half-width (，→, etc.), applied to both anchors and node text. Matching keeps unique-prefix semantics: zero hits → "not found" with closest-node hints; more than one hit → "AMBIGUOUS".
• Restart-safe sequential archives: the next number is derived by scanning the session's spill directory (max+1) — gap-free; the backend's random hex prefix makes filename collisions impossible.
• Paired cleanup: the tool-call message (carrying the full summary argument) and its tool/result are each replaced by one tiny shadow message, so the checkpoint text never appears twice on the surface (skipped when the message holds more than one tool call).

Compatibility

• Built and verified against DeepSeek Harness 0.1.0-rc.6 (@deepseek-ai/dsh-compaction-basic@0.1.0-rc.6).
• Only one compaction per session at a time (the engine transaction is serialized); anchors re-resolve on every call, so later compactions never go stale after earlier checkpoints replaced old nodes.
• With a local spill backend the root is fixed; other backends degrade gracefully (no root field → in-memory counter), and compaction itself is unaffected.

License

MIT. The patch derives from @deepseek-ai/dsh-compaction-basic and related DeepSeek Harness packages (MIT, Copyright DeepSeek) — see LICENSE.