DeepSeek Harness Plugin: dsh-agent-control

Introduction¶

DeepSeek Harness (DSH) uses a plug-in architecture. During development and debugging, deleting a session, deleting a single conversation turn, and restarting or shutting down an instance are three typical “destructive operations.” These operations are usually scattered across different modules and lack unified confirmation and failure-semantics management, so they can easily lead to misjudgment when operated.

The ventisyn/dsh-agent-control plugin consolidates these three categories of operations and provides a unified confirmation mechanism and error-handling logic. It does not rely on internal kernel structures and only uses public APIs, aiming to provide developers with more controllable session management and process-control capabilities.

Core Features¶

The plugin primarily includes the following capabilities:

1. Delete session: Remove a session without leaving residuals. It recursively cleans up all sub-agent sessions derived from that session (including directories, workspace accounting, and projection cache). If any sub-agent still has a session resident in memory, the deletion operation is rejected. The plugin does not touch data from other plugins (such as event records from approval-type plugins) or content-addressed shared attachments.
2. Delete a conversation turn: Remove a completed conversation turn (the question, the reply, and tool records) from the model’s visible context. This process is similar to manual compression in DSH; it replaces the visible content by appending an independent transaction, so the model can no longer see the original content. The deleted turn remains in logs and attachments, so this is not secure deletion.
3. Hot restart: Allow the model or user to restart the DSH process. The restart is executed after the current task finishes, and the session automatically continues after the restart. This is mainly used to apply changes after modifying host plugin code.
4. Shut down instance: Cleanly stop the entire DSH instance, equivalent to closing the window directly. This is usually triggered by the user on the settings page.
5. Component toggles: The plugin list includes four configuration rows (core + session/turn/restart), and each row can be disabled individually. After disabling, the corresponding route disappears, and the UI entry disappears as well.
6. Status probes: Provide read-only endpoints such as GET /api/agent-control/sessions to query session status or confirm whether components are registered successfully.

Installation and Enablement¶

Install using the dsh command-line tool and specify the profile name:

# 安装最新版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control

# 锁定到特定版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control#<完整版本号>

# 本地开发模式
dsh plugin --profile <profile 名> add link:<本地 clone 路径>

Notes:
* If deletion-type plugins are already installed in the profile, remove them first; otherwise, duplicate delete buttons will appear in the UI.
* After installing or modifying host-side code, you need to restart dsh web to load new routes.

Typical Usage¶

UI Operations¶

• Delete session: Select “Delete session” from the “…” menu in the session list, or operate it on the settings page.
• Delete a turn: Click the trash can button next to each finished reply.
• Restart/shut down: In the “Agent Control” area on the settings page, click “Restart DSH” or “Shut down instance.” A confirmation checkbox must be selected before the operation.

API Endpoints¶

The plugin provides HTTP endpoints, but it has no Harness authentication. It is recommended to bind only to the loopback address or perform Origin validation.

# 查询会话列表
curl http://127.0.0.1:<端口>/api/agent-control/sessions

# 热重启
POST http://127.0.0.1:<端口>/api/agent-control/restart
Content-Type: application/json

{"reason": "修改了宿主插件代码"}

# 关闭实例
POST http://127.0.0.1:<端口>/api/agent-control/shutdown

Component Toggles¶

In the plugin list, there is a toggle on the right side of each row.
* dsh-agent-control (core): Responsible for delivery and initialization.
* dsh-agent-control/session: Responsible for session management.
* dsh-agent-control/turn: Responsible for turn management.
* dsh-agent-control/restart: Responsible for hot restart and instance shutdown.

After disabling a row, restart the instance to make it effective. Disabling the “hot restart” row removes both the restart and shutdown buttons.

Cautions¶

1. Deleting a turn is not secure deletion: The content of the deleted turn remains in the session log and attachment storage; it is only invisible to the model.
2. Attachment cleanup limitation: Deleting a turn does not clean up attachments because the kernel has no public cleanup interface.
3. HTTP endpoint authentication: The endpoints have no Harness authentication and rely only on Origin/custom header validation. Do not bind webServer to 0.0.0.0, to avoid exposing restart or shutdown endpoints.
4. Launcher orphan processes: If the instance was started by the desktop launcher (DSHL), the process becomes orphaned after restart. The launcher cannot recognize the new process; manually terminate the old process and then restart it.
5. Restart and shutdown:
   • During a restart, the page is briefly unavailable.
   • Shutting down an instance interrupts all sessions and background tasks, and it does not automatically restart the instance.
   • Compressed turns may not be deletable individually.

Summary¶

dsh-agent-control unifies destructive operations, simplifying the development and debugging workflow of DSH plugins. It provides flexible component toggles and a unified confirmation mechanism in both the UI and API layers. Developers should pay special attention to its non-secure deletion behavior and compatibility issues with the launcher.