Preface

In the development workflow of DeepSeek Harness (DSH), long sessions often do not end with a “crash,” but with “soaring costs.” The platform automatically compresses the session when context usage reaches about 80%, usually at a moment when the user can no longer intervene. dsh-context-guard aims to address this issue: it intervenes at the end of a turn, uses the contextPressure projection computed by the official dsh-token-meter, alerts the user to end the current session and start a new one when session usage reaches a threshold, and automatically generates a handover document.

Plugin Introduction

This is a DSH workflow plugin maintained by user 2JumpSinA. It reads data from the official token-meter, triggers a warning when session usage is too high, and automatically drafts a machine-fact handover block written to the session’s working directory. Its core value lies in “zero context tax” — it does not register tools with the model, does not inject prompts, does not send additional requests, and performs all calculations and read/write operations entirely within the host process.

Core Capabilities

  • Consuming Official Projections: Directly reads the contextPressure data generated by dsh-token-meter.
  • Automatic Handover Drafting: When session usage exceeds warnRatio (default 45%), the plugin creates or overwrites HANDOVER.md in the session’s working directory. It refreshes the document for every additional 5 percentage points afterward.
  • Zero Context Tax: It does not register tools visible to the model, does not inject prompts, does not generate additional API requests, and does not increase token consumption on the model side.
  • Machine-Fact Recording: The handover document contains the session ID, title, working directory, usage rate, invocation count, billed cost, list of files written during the current session, and previews of the most recent few prompt and response turns.
  • Bilingual Support: Built-in Chinese and English runtime copies, automatically detected based on context.

Usage and Configuration

  • Default Trigger: handoverOnWarn defaults to true, and warnRatio defaults to 0.45 (45%).
  • Handover Path: The default path is HANDOVER.md.
  • Push Configuration: pushChannel defaults to 'none', meaning messages are not pushed externally.
  • Typical Flow: When usage crosses the 45% threshold, the plugin emits a warning at the end of the turn and generates HANDOVER.md in the current directory; it refreshes the file as it crosses 50%, 55%, and so on.

Permissions and Security

  • Working Directory Writes: The plugin writes the handover document to the session’s working directory. This directory may contain sensitive information (such as file paths and prompt fragments), so it is recommended to add HANDOVER.md to .gitignore or point handoverPath outside the repository.
  • Atomic Writes and Permissions: It uses an atomic write mode (temporary file + rename), and file permissions are strictly limited to 0o600.
  • Boundary Checks: It refuses to write to non-existent parent directories, non-text files (such as .json/.yml), and symbolic links pointing elsewhere.
  • Error Handling: Any write failure is only recorded as status and does not affect badge display or push functionality.

Technical Specifications

  • Package Name: @2jumpsina/dsh-context-guard
  • Version: 0.3.4
  • Runtime Environment: Node.js ^22.19.0 || >=24.0.0
  • Dependencies: Requires @deepseek-ai/schemastery as a peer dependency.