@deepseek-ai/dsh-checkpoint

Zero-LLM compaction for DSH agent presets. Replaces the stock replay summarizer with a three-tier fold:

1. Checkpoint file — if the model wrote checkpoint_update recently (freshness validated against the newest work event in the shadowed span), the file content IS the fold summary. Verbatim, instant.
2. Mechanical span digest — otherwise the engine distills the exact shadowed span (input.messages, already tool-pair-balanced, tail excluded by the base engine) into a capped skeleton: [USER] asks, [ASSISTANT] steps, [TOOL] calls with args, [TOOL-ERROR] failures. No LLM call.
3. LLM fallback — only when there is literally nothing to distill.

A fold therefore never waits on model inference, regardless of whether the model maintained its checkpoint.

Details that matter

• Adaptive budget: the digest scales with the span (min(6000 chars, inputChars/2 − 300)) so sliver spans just over the fold threshold produce a tiny digest instead of failing the base engine's summary is not smaller than the shadowed content guard.
• STATE-CARRIED: a prior fold's injected <compacted-summary> message is detected by its preamble and carried once as a clipped [STATE-CARRIED] line instead of being re-ingested verbatim (no summary-of-summary snowballing).
• Boilerplate filters: harness messages wrapped in <system-reminder> or starting with Current runtime context are skipped, not treated as asks.
• Freshness rule: a checkpoint is accepted only if its mtime is newer than the newest work event (assistant/message | tool/result) in the shadowed span, minus a 60s epsilon for the checkpoint's own tool-result latency. Bare user prompts and idle time never invalidate a checkpoint.

Install

docker exec <container> npx dsh plugin --profile web add @deepseek-ai/dsh-checkpoint

(Or vendor it: copy the package under ~/.dsh/profiles/web/plugins/ and add a file: dependency in ~/.dsh/profiles/web/package.json, then restart.)

Preset row

Swap your preset's compaction engine row:

- id: compaction
  name: cordis:group
  group: true
  isolate:
    compaction: true
    toolResultPruner: true
  config:
    - id: checkpoint-compaction
      name: '@deepseek-ai/dsh-checkpoint'
      config:
        thresholdRatio: 0.62   # fold point, fraction of contextWindow
        retainRatio: 0.1       # recent tail kept verbatim
        maxTokens: 4096        # budget for the LLM fallback only

Tuning the ratios

The threshold is measured against total input (system prompt + conversation), not conversation alone. Keep this invariant:

sys_prompt + digest(~1.6K) + retainRatio × window  ≤  thresholdRatio × window − work_room

With a ~9.5K-token system prompt on a 36864 window, 0.62 / 0.1 leaves ~8K of work room between folds. Too little room → fold-every-step churn; too much tail → the same. The base engine rejects unknown config keys, so these three are all you can set.

Pairing: let the model write checkpoints

Tier 1 needs a tool that writes ~/.dsh/storages/checkpoints/<sessionId>.md (fallback active.md). The companion plugin @deepseek-ai/dsh-tool-search ships checkpoint_update plus a staleness nudge that reminds the model to use it. Without a writer tool the engine still works — every fold is a tier-2 digest.

Layout

• lib/index.js — CheckpointCompactionEngine (default export, subclasses BasicCompactionEngine; hook: summarize(input, agent, signal)), plus mechanicalDigest / checkpointTextFor / shadowBoundaryMs internals.

Tests

16-case unit suite covers extraction, STATE-CARRIED clipping, boilerplate filters, span budget caps, and adaptive tiny-span budgets. Run against an installed copy:

node --input-type=module -e "import Engine from '<installed>/lib/index.js'; /* ... */"