Introduction

DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. When building agents for long conversations or complex tasks, automatically determining when a session is suitable for handoff to a human or another process is a common requirement. dsh-session-handoff is a host plugin (thin adapter layer) that does not implement specific handoff logic. Instead, it observes session state, triggers suggestions when conditions are met, and guides the user or system to complete the handoff.

Plugin Positioning and Core Value

This plugin is developed by maintainer realpkuasule and belongs to memory-related tools. Its core value lies in decoupling “session health observation” from “handoff action triggering.” Through a series of threshold checks, when a session enters certain stages (for example, too many steps or too many retries), it appends suggestions to the tail of the session using deterministic templates, works with approval gating, and finally invokes the global harness-automation CLI to perform the actual operation.

Installation and Activation

This plugin supports installation through DSH’s standard plugin mechanism. Please ensure your Node.js version is 20 or higher.

dsh --profile web plugin add github:realpkuasule/dsh-session-handoff

After installation, the plugin is automatically mounted into the configuration. You can run dsh --profile web --dump-config to check whether dsh-session-handoff appears in the composition tree, then restart the web process to activate it.

Core Features

The plugin mainly includes the following capabilities:

  1. Session metrics observation: The projection unit sessionHandoff continuously records session data such as turns (turns), steps (steps), llmMs (elapsed time), titles, retries (retries), and splices (prefix cache operations).
  2. Threshold-based trigger detection: The plugin reads threshold configuration from the policy file. When observed metrics (for example, turns ≥ 12, steps ≥ 150, llmMs ≥ 30min) exceed the thresholds, the state is judged as “handoff suggestion.”
  3. Append-Only suggestion injection: After a threshold is hit, the plugin injects a deterministic suggestion in the next open turn. This injection strictly follows append-only discipline. The message content is rendered from a fixed template (without timestamps or random numbers), and a fingerprint deduplication mechanism ensures it is not appended repeatedly.
  4. Approval gate control: After the suggestion is injected, the plugin requests ctx.approval within the same turn. Only when allowed-once is approved does it invoke the CLI to perform the handoff; rejection or cancellation does not execute any operation.
  5. Invoking the harness-automation CLI: The handoff execution is completed by the global harness-automation session handoff command. The plugin only parses its JSON output.

Usage Flow and Limitations

The plugin works through the following steps:

  1. Observe: Subscribe to the session’s change feed and continuously update the projection view.
  2. Evaluate: Calculate the delta between the current view and the policy file thresholds.
  3. Trigger: If no threshold has been hit and the fingerprint does not exist, put the session into pending and inject the suggestion in the next open turn.
  4. Execute: After the user approves within the turn, the CLI performs the handoff.

Important constraints and notes:

  • Read-only policy: When reading the policy file (default: .harness/session-workflow.yaml), the plugin never modifies its contents and uses it only as a read-only triggering basis.
  • Injection discipline: Injected messages may only be appended to the tail of the history and cannot be appended when the state has not changed (to prevent zero-state writes).
  • Approval timing: Approval requests are only valid within an open turn. The plugin has no background timers and does not terminate the session unilaterally.
  • Configuration parsing: The threshold parser in the project policy file accepts only scalar numeric keys under the thresholds: block and does not support complex YAML structures.

Use Cases

This plugin is suitable for scenarios that require automated management of long-session lifecycles in the DSH ecosystem, strict auditing of the handoff process, and separation of handoff logic from observation logic. Because the plugin only observes and triggers, and execution logic depends entirely on an external CLI, it is suitable for teams that need flexible handoff policy configuration.

Summary

dsh-session-handoff is a lightweight adapter focused on the “observe–evaluate–trigger” chain. Through strict append-only injection and fingerprint deduplication, it ensures the stability of session state. Through approval gating and CLI invocation, it ensures the handoff process remains controlled. If you are using DSH to build applications that require automatic management of session progress, this plugin provides a standardized entry point.

  • Project directory: https://www.skillhub.cn/plugins/realpkuasule/dsh-session-handoff
  • GitHub repository: https://github.com/realpkuasule/dsh-session-handoff