@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 appends the log-only checkpoint/mark session event) 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.

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?) — append a durable checkpoint/mark event to a session log and return its seq. The event is log-only (no surfaceOp), so compaction or a later fold never shadows it and the marker stays locatable no matter what happens between mark and rewind. A numbered turn records the open turn the marker was appended in; null marks an idle session.
checkpoint tool — { objective?: string } → { seq }. 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 { seq } 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 appears in the model-visible history (log-only).

KV Cache effect

Prefix-stable: the tool schema is fixed; marker appends do not 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.

dsh-checkpoint