dsh-session-cleaner: DSH Session Recycle Bin and Cleanup Manager

Introduction¶

DeepSeek Harness (DSH) adopts a plugin-based architecture, and its extension capabilities rely on community plugins. In the Web GUI, the native interaction lacks session deletion capability, preventing users from properly managing obsolete or test sessions and potentially causing data loss due to accidental operations. dsh-session-cleaner fills this native gap by adding session deletion capability to DSH, providing a two-stage recoverable deletion design through native sidebar interaction. It also includes built-in protections against accidentally deleting same-named sessions, conversation preview, and periodic automatic purging, while keeping the interface theme consistent with DSH.

Core Features¶

• Reversible Trash: Supports moving sessions to the trash (the physical directory is moved to dsh-home/.session-cleaner-trash), allowing sessions to be restored or permanently deleted at any time.
• Same-Name Deletion Protection: Precisely extracts the sessionId without relying on title guesses. The confirmation dialog displays same-name session summaries and a comparison of their first instructions to prevent accidental deletion.
• Conversation Content Preview: Uses zstd decompression and JSONL extraction to display the session title, turns, and user/assistant messages. It automatically filters system-injected messages to ensure the first user instruction is a real human prompt.
• Periodic Automatic Purging: Can be enabled or disabled. Retention days (1–3650) and check interval (15–1440 minutes) are configurable. The trash displays remaining days and expiration status.
• Theme Consistency: Embeds official design tokens (light/dark). Components use --dsw-alias-* semantic variables to ensure a unified UI style with DSH.
• Security Hardening: Includes Session ID path traversal validation. It determines active sessions based on the hard signals openStep/pendingCalls from projcache, rejecting deletion of unclosed steps.

Installation and Enablement¶

This plugin is published as the scoped package @luchenglong/dsh-session-cleaner.

Install command:

dsh plugin --profile web add @luchenglong/dsh-session-cleaner

After installation, the bundle patch layer automatically registers the plugin (dsh.bundle.patch → cordis.patch.yml, id: session-cleaner). DSH automatically hot-reloads. After refreshing the page once (F5), a “Trash” entry and menu item appear in the sidebar.

Verify installation:
Access GET /api/session-cleaner/sessions. A 200 response indicates that the plugin is active.

Daily Operations¶

Move to Trash¶

Click the “⋯” menu on any session in the sidebar and select “Move to Trash”.

Confirmation¶

The system displays a confirmation window. The window shows the full sessionId and the first user instruction. If same-named sessions exist, a yellow warning area lists their respective instructions for comparison to prevent accidental deletion.

Restore Session¶

Click “Trash” at the bottom of the sidebar, find the corresponding session, and click “Restore”.
Note: Restored sessions reappear in the sidebar list only after restarting DSH.

View Conversation¶

On the management page (/session-cleaner), click “💬 View Conversation” to expand an inline card and view the conversation content.

Permanently Delete¶

Click “Purge” inside the trash, or handle it through the periodic automatic purging feature.

Periodic Purging Settings¶

In the settings card of the “Trash” section on the management page, you can configure periodic automatic purging:
- Switch: Enable or disable automatic purging.
- Retention Days: The number of days a session remains in the trash after being moved there.
- Check Interval: The time interval (in minutes) between system checks that clean up expired sessions.

The configuration is persisted to dsh-home/session-cleaner-settings.json. The default configuration is enabled, retain for 30 days, and check once every 60 minutes. The management page also provides a “Purge Expired Now” button.

HTTP API¶

Example: Move to Trash

$base = 'http://127.0.0.1:58644'   # 请替换为实际 GUI 地址

Invoke-RestMethod "$base/api/session-cleaner/delete" -Method Post -ContentType 'application/json' `
  -Body '{"sessionId":"session-xxxxxxxx","confirm":"DELETE"}'

Notes¶

1. Session Restoration: Restored sessions reappear in the sidebar list only after restarting DSH, because the host workspace registry has no external adoption API.
2. Unclosed Step Protection: Sessions with unclosed steps are rejected for deletion to prevent data truncation. They can be deleted only after their state has settled.
3. Active Session Detection: The isLive determination must not rely on SessionStore’s in-memory loaded state (DSH keeps opened sessions resident in memory, causing all idle sessions to be misjudged as active). This plugin only recognizes projcache’s openStep/pendingCalls as hard signals.
4. Automatic Purging Is Irreversible: Automatic purging is a direct background deletion operation. Once executed, it cannot be restored.
5. Scoped Package Conflict: npm has an unscoped package with the same name, dsh-session-cleaner (published by fountunt), and the two have different functionality. This plugin is @luchenglong/dsh-session-cleaner, so the two do not conflict.

Conclusion¶

dsh-session-cleaner provides a complete session trash solution, resolving DSH’s lack of native session deletion capability. Through sidebar interaction, same-name protection, conversation preview, and periodic cleaning, it helps developers manage session data more effectively.

• GitHub Repository
• Community Directory