@dpskh/tool-rewind — exploration fold for the DeepSeek Harness

English | 中文

One package, one entry plugin. Mounting @dpskh/tool-rewind provides ctx.rewind (a service that folds everything since the most recent checkpoint mark into an auto-generated report) and the model-facing rewind tool over it. The fold shadows the exploration's surface range with the report — the same surfaceOp: { op: 'replace' } mechanism the DeepSeek Harness compaction seam uses — so subsequent requests no longer carry the exploration's intermediate steps (reads, searches, experiments), while the durable log keeps the full exploration for audit. The report is produced by ctx.llm (auto-generated); the mark is owned and served by the sibling @dpskh/tool-checkpoint plugin (ctx.checkpoint.latestMark / hasActive / completeFold). This plugin writes no session events of its own — the fold commits only the core-vocabulary user/message replacement, so the durable session log stays readable by any harness. No upstream package is modified.

Configuration

- id: tool-rewind
  name: '@dpskh/tool-rewind'
  config:
    toolName: rewind                # model-facing tool name (default rewind)
    maxTokens: 1024                 # summarization output budget
    maxSummarizationRetries: 2      # empty-completion retries before failing
    summarizationProvider: deepseek # optional override of the routed provider
    summarizationModel: deepseek-chat
    reportLanguage: en              # en | zh (report instruction language)

Provider/model resolution order for the report call: configured overrides, then the session's last routed request/header config, then the agent's options. Missing all three fails loud.

The report call runs with thinking disabled when the route exposes an off reasoning effort — condensing an exploration is mechanical, and a reasoning model's thinking tokens otherwise compete with the report text under maxTokens (thinking can exhaust the budget before any text starts, leaving an empty completion). Empty completions retry up to maxSummarizationRetries; an exhausted budget rejects with a message carrying the finish reason and token usage, which the rejection message preserves.

Working together

The fold needs a marker: mount both plugins so rewind can collapse the exploration anchored by a checkpoint. rewind alone has nothing to fold and fails with a no-checkpoint error; checkpoint alone records inert markers.

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

Contract

• ctx.rewind.rewind(agent, signal) — read the session's latest mark through ctx.checkpoint; select the surface span after it (never folding the rewind call itself, never splitting a tool-call/result pair at the trailing boundary); summarize the span over ctx.llm; then commit, in one synchronous block, a replacement user/message carrying the report with source marker { kind: 'plugin', plugin: 'rewind' } (isRewindReportSource recognizes it) and stamp the mark folded through ctx.checkpoint.completeFold. Failures write nothing — the region stays intact, the mark stays active, and the fold is retryable — and reject with a classified RewindError (NO_CHECKPOINT, EMPTY_REGION, UNBALANCED, FOLD_IN_PROGRESS, CHANGED, SHRINK). A per-session in-process lock rejects concurrent folds. A mark taken mid-call — the checkpoint tool runs between its own tool-call and result — leaves that result orphaned right after the mark; selection skips exactly that node, so the checkpoint call's own pair stays visible and the fold starts at the exploration that follows. Exploration calls issued in parallel with the checkpoint (same assistant message) leave their results behind the mark too; those are folded, so a parallel exploration never collapses into an empty region.
• rewind tool — no arguments → { markId, foldedNodes, start, end, foldedChars, reportChars }, where foldedChars is the model-visible text the folded region contributed (assistant text, reasoning, tool-call arguments, and tool outputs) and reportChars is the replacement report's length — the shrink accounting is visible in every result and error. Render intent: generic card.
• Turn guard — while the session has an active (unfolded) checkpoint mark, agent/turn-stopping injects a standing warning into the agent's next-step inbox (one per agent per turn), so the turn cannot end until rewind folds the exploration. Activeness is read through ctx.checkpoint. A rewind that legitimately fails (e.g. an empty region) cannot trap the turn in a warning loop.

Model Experience

Directly: the rewind tool call and its fold result. The replacement report message is model-visible from the next request on; the exploration's durable events stay in the log but out of the model-visible surface. A tool:rewind system-prompt section makes fold discipline a standing instruction (rewind immediately after the marked exploration, before unrelated work).

KV Cache effect

The report call reuses the session's system prompt and tool schemas so it stays a prefix of the last routed request (warm prefix cache). The fold itself shifts the model-visible prefix of subsequent requests by design.

Known Limitations and Deferred Work

• Shrink check is char-based — the report must be shorter than the folded region's model-visible text (measured in characters, not tokens); the yardstick counts every block the model reads: assistant/user text, reasoning, tool-call arguments, and tool outputs (recursively). A token-meter-based check would be more precise; image blocks carry no text yardstick and are conservatively ignored.
• Empty completions on routes without an off reasoning effort — such routes keep their default thinking; if thinking exhausts maxTokens the completion is empty and only the retry budget saves the fold.
• One fold per marker — folding the same marker twice is rejected as an empty region; a new exploration needs a fresh checkpoint.
• Mid-exploration compaction — if automatic compaction shadows part of the exploration before rewind runs, the fold covers whatever remains on the surface; the storage-resident mark survives either way.