@dpskh/tool-checkpoint — checkpoint marker for the DeepSeek Harness

English | 中文

One package, one entry plugin. Mounting @dpskh/tool-checkpoint provides ctx.checkpoint (a service that durably records a checkpoint mark in the plugin-owned storage domain, keyed by session id) and the model-facing checkpoint tool over it. The marker records the conversation position an exploration starts from; the sibling @dpskh/tool-rewind plugin folds everything after the marker into an auto-generated report, keeping the exploration's noisy middle (reads, searches, experiments) out of the model-visible context while the durable log retains the full exploration for audit. This plugin never folds anything itself — the marker stays inert until a rewind.

The mark is not a session event: it lives in the checkpoint storage domain (~/.dsh/storages/checkpoint.json), so the durable session log stays purely core-vocabulary and remains readable by any harness — an out-of-repo plugin event would be refused by harnesses whose vocabulary lacks it. rewind consumes marks exclusively through this service.

Configuration

- id: tool-checkpoint
  name: '@dpskh/tool-checkpoint'
  config:
    toolName: checkpoint   # model-facing tool name (default checkpoint)

Working together

The marker only earns its keep with a fold: mount both plugins so rewind can collapse the exploration the marker anchors. checkpoint alone records inert markers; rewind alone has nothing to fold and fails with a no-checkpoint error.

- id: tool-checkpoint
  name: '@dpskh/tool-checkpoint'
- id: tool-rewind
  name: '@dpskh/tool-rewind'        # https://github.com/dpskh/dsh-rewind
  config:
    reportLanguage: en              # en | zh report instruction language

Contract

• ctx.checkpoint.mark(session, objective?) — record a durable mark for the session in the plugin-owned storage domain, keyed by session id, and return { id, logLength }. id is the plugin-owned monotonic marker identity; logLength is the session log length at mark time (the fold anchor: the seq of the first event after the marker). A numbered turn records the open turn the marker was taken in; null marks an idle session. The mark lives outside the session log, so compaction or a later fold never shadows it and it stays locatable no matter what happens between mark and rewind.
• ctx.checkpoint.latestMark(sessionId) / ctx.checkpoint.hasActive(sessionId) / ctx.checkpoint.completeFold(sessionId, id) — the consumption surface rewind uses: read the latest mark, ask whether a fold is still owed, and stamp a mark folded after a successful fold.
• checkpoint tool — { objective?: string } → { id, logLength }. The model calls it before an exploration whose intermediate steps would clutter the context, then rewind folds everything since the mark into an auto-generated report. Render intent: generic card.

Model Experience

Directly: the checkpoint tool call and its { id, logLength } result. The tool description teaches the mark-then-rewind workflow; a tool:checkpoint system-prompt section makes it a standing instruction (mark before any investigation that will take more than one tool call, rewind before finishing the turn). The marker itself never enters the model-visible history and never enters the session log.

KV Cache effect

Prefix-stable: the tool schema is fixed; markers are storage records, not session events, so they never alter the request prefix.

Known Limitations and Deferred Work

• Marker without a rewind is inert — a checkpoint that is never rewound costs nothing but leaves the exploration in context; the workflow depends on the model pairing mark and rewind.
• One fold per marker — rewind folds from the most recent marker; folding the same marker twice is rejected as an empty region.