dsh-asc

English | 中文

dsh-asc (full name DeepSeek Harness Agentic Surface Compaction) is a context-compaction plugin for DeepSeek Harness: the model itself decides when and what to compact, and every compaction decision is committed as a durable session-log replacement event (surfaceOp: replace) — replayable, searchable, and reversible.

Inspired by the model-driven compaction philosophy of opencode-acp, but built on DSH's event-sourced log: compaction creates no side-state files, decompression is log replay, and search covers the full log including compacted originals.

Install

Prerequisites: a working DeepSeek Harness installation (dsh CLI available); Node.js ^22.19 or >=24.

From npm (recommended):

dsh plugin --profile <name> add dsh-asc

From GitHub — to use a commit newer than the npm release:

dsh plugin --profile <name> add github:lmst2/dsh-asc

dsh plugin adds the plugin to the profile and enables it automatically based on the dsh.bundle declaration in the package; the tools and the system prompt load together with that profile.

Restart required: after installing, restart the running DeepSeek Harness service.

Other install options

From source — to modify the plugin itself, or to contribute:

git clone https://github.com/lmst2/dsh-asc.git
cd dsh-asc
pnpm install
pnpm build
dsh plugin --profile <name> add "link:$(pwd)"

Disabling the basic backend

ctx.compaction allows only one provider at a time. Disable the default basic backend in your profile's own cordis.patch.yml:

- id: compaction-basic
  disabled: true

Optionally mount the invariant companion and the full-text-search backend:

- insert:
    - id: dsh-asc-invariant          # runtime invariant checks (optional, recommended)
      name: "dsh-asc/invariant"
    - id: session-query-sqlite       # context_search full-text backend (optional)
      name: "@deepseek-ai/dsh-session-query-sqlite"

Usage

After installing and restarting, no configuration is required — the plugin:

• injects the context-management discipline into the system prompt (judgment rules, tool usage, tiered compaction cadence), so the model actively manages context from the very first turn;
• injects nudge prompts on demand when context usage runs high (cadence-gated; iteration nudges additionally require real token growth — no per-turn nagging);
• provides deterministic degradation (LLM summarization, plus tool-result pruning when the optional upstream pruner is mounted) on overflow or manual compaction, without requiring model cooperation.

The plugin provides five model tools:

Tool	Purpose
context_status	context usage, tiered checkpoints, system/dialogue composition, recommended ranges, recent surface nodes
context_compress	replace a surface range with a checkpoint you write (batching supported; tool-call pairs auto-extended; quality gate)
context_decompress	undo a compaction: the original text returns to the surface at the checkpoint's own position (tier-aware; full: true reaches raw content)
context_recap	re-read checkpoint summaries without decompressing the originals
context_search	full-text search over the whole log (including compacted content)

Compacted content is never lost: the originals stay in the session log and can be decompressed or searched at any time.

The system prompt ties the tools into one operating loop: capture consumed raw work into tier-1 checkpoints, distill settled tier-1 piles into tier-2 decisions and tier-2 piles into a tier-3 fact index. Every checkpoint text carries its topic and Compaction id, so when a visible summary already points at the needed detail the model decompresses that block directly; context_search is used only when no visible summary says where a detail lives, and decompression always proceeds one tier at a time.

How it works

• Event sourcing: a compaction is a transaction in the log (compaction/start → compaction/summary → replaced user/message → compaction/end); no side state.
• Tiered compaction: checkpoints have tiers (T1 full detail → T2 distilled decisions → T3 bare facts); summaries get thinner as they are reused.
• Reversible: decompression replays the events shadowed in the log and commits one in-place replacement event; no side state is needed.
• Auditable: who compacted what, the full summary text, and the token cost are all in the log.

Repository layout

src/
  index.ts      plugin entry: registers ctx.compaction + the five tools
  config.ts     strict config validation
  types.ts      shared config and result types
  events.ts     session-event vocabulary documentation (no custom members)
  invariant.ts  runtime invariant companion (subpath export)
  engine/       the compaction engine core (engine, region, tier,
                quality gate, fallback, prompt, restore)
  policy/       protected-node policy and the nudge state machine
  tools/        the five model tools
  utils/        shared text helpers
tests/          vitest suites
docs/           usage, design, analysis, e2e-validation

Documentation

Doc	Contents
docs/usage.md	install, configuration, model experience, operations
docs/design.md	implemented contract: events, tools, automatic behavior, protection, invariants
docs/analysis.md	comparison of DSH and opencode-acp context management

License

MIT. Algorithmic inspiration from DeepSeek Harness (MIT); only the ideas of opencode-acp (AGPL) are used, no source code. See NOTICE.