Preface

DeepSeek Harness (DSH) adopts the philosophy of “everything is a plugin.” In long-running agent sessions, context window usage, compression count, and cache hit rate change as dialogue turns increase, which can easily lead to token waste or performance degradation. The dsh-session-health plugin monitors session health in real time via a floating button in the lower-right corner, helping developers decide whether to reopen a session or generate a handoff file.

Installation and Enablement

This plugin is a DSH bundle (containing dsh.bundle.patch and dsh.client). After installation, the web profile process must be restarted for the changes to take effect.

  1. Run the following command to install the plugin:
dsh plugin --profile web add github:CJL-1995/dsh-session-health
  1. Restart the dsh web process. A “Session Health Reminder” button will appear in the lower-right corner.

Feature Overview

After installation, a draggable floating button will appear in the lower-right corner. A long press (about 260 ms) enables dragging for positioning; a quick click opens the health report panel above the button.

The report panel includes the following core data:

  • Health Score: A 0–100% score, categorized into green, yellow-green, orange, and red tiers.
  • Context Window Usage: A red/green progress bar indicating usage percentage, with the percentage and window size included.
  • Compression Analysis: Displays the compression count, with a “line chart since last compression” (x-axis: compression index, y-axis: turn count).
  • Invocation Trends: Total tool calls per turn / cumulative average tool calls; total steps per turn / cumulative average steps.
  • Token Consumption Statistics: Uncached input, cache reads, output, reasoning, and total (cumulative across the session).
  • Latency Analysis: LLM generation time, tool execution time, and total active latency.
  • Step Details: A reverse-chronological list of steps, showing the duration and invoked tools for each step.
  • Top Consumers Ranking: Ranked by tool, listing the top consumers of tokens and latency.
  • One-click handoff generation for sub-healthy sessions: When the health score is below 60%, the panel additionally shows a “Generate handoff and reopen session” button.

Health Score Logic

The health score is calculated using a three-factor weighted model, as follows:

Health Score = 100 − Context Usage Deduction (40%) − Compression Count Deduction (30%) − Cache Hit Rate Deduction (30%)
  • Context Usage: Linear deduction after usage exceeds 30%; 100% usage deducts the full 40 points.
  • Compression Count: Linear deduction from 0 to 5 compressions; 5 or more compressions deduct the full 30 points.
  • Cache Hit Rate: Direct full 30-point deduction when below 50%; linear deduction from 50% to 100%; no deduction at 100%.

Scoring tiers:
* ≥ 80: Healthy
* 60 – 79: Fair
* 40 – 59: Sub-healthy
* < 40: Unhealthy

Typical Usage

  1. View Report: Click the button in the lower-right corner to view the current session metrics.
  2. Handle Sub-healthy Sessions: If the health score is below 60%, click the “Generate handoff and reopen session” button on the panel.
  3. Automatic Handling: The plugin sends a summary prompt to the current session. The Agent generates a HANDOFF.md file and returns the disk path, after which the session is reopened.

Technical Details

  • Architecture: The host side (index.js) registers a sessionHealth projection via sessionProjections, incrementally reducing session events into a pure JSON state. The client side (client.js) loads and registers the plugin via window.__ModuleLoader__ into shell.overlay, and reactively reads the report.
  • Bundle Type: dsh.bundle.patch + dsh.client.

Applicable Scenarios and Notes

This plugin is suitable for developers who need fine-grained control over session cost and state. When using it, note that the plugin runs with the permissions of the current dsh web process. It is recommended to review the source code and license (MIT) before installation.