Skip to main content

dsh-session-manager

41Stars3Forks0Issues2Watchers

Adds complete session management for the DSH Web interface: trash deletion, archive recovery, continue/pause, unread marking, fork, workspace management, and context compression threshold.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
MIT
Branch
main
ai-workerdeeepseek-harness-pluginsdeepseek-harnessdeepseek-harness-plugindshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add dsh-session-manager

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin dream12347/dsh-session-manager for me: review the repository at https://github.com/dream12347/dsh-session-manager first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

Adds complete session management capabilities to the DSH Web interface: accessible from both the Settings page and conversation top. Supports deletion (with recoverable trash or permanent purge), restoring archived sessions, resuming/pausing sessions, viewing recent activity stats, opening log directories, unread/read marking, forking to new chats, workspace grouping and sorting management, and a global context compaction threshold that applies uniformly to all Agent presets.

Core Features

  • Delete sessions to trash (keeps most recent 10, earliest automatically purged permanently), supports restore or permanent deletion
  • Restore "archived" sessions from the Settings page back to the main list
  • One-click resume idle sessions or pause running sessions
  • View session recent activity stats in a centered popup (turns, user messages, assistant messages, all tool calls, activity window)
  • Open session's log directory in system file manager
  • Display four-state dots next to session row titles (manual unread blue, official waiting-for-input amber, official completion-notice green, running spinner), also inject blue unread dot into official sidebar
  • One-click fork current session to new chat (calls official sessions.fork)
  • Workspace grouping displays sessions, sorted by last usage time within groups, supports drag-to-reorder, pin to top, rename, delete workspace
  • Adjust context compaction threshold (17%–90%) in "General Settings", applies uniformly to all Agent presets and persists

Technical Implementation

  • Language: TypeScript
  • Key Dependencies: @deepseek-ai/cordis (plugin runtime), @deepseek-ai/dsh-host-webserver (HTTP routing), zod (request/storage domain schema), @deepseek-ai/dsh-storage-domain (persistence), react 18 (client UI)
  • Architecture Pattern: Standard DSH plugin dual-end structure. src/index.ts is the host side, exposes 7 HTTP routes via ctx.webServer.register (/delete /restore /purge /trash /open-folder /pause /compaction-threshold), and applies threshold on every step via ctx.on('agent/pre-step', ...) hook. src/client/index.ts is the client side, registers to three official slots via ctx.slots.inject: settings.section (independent "Session Management" section), settings.general.item (compaction threshold slider), conversation.session.header.utilities ("Conversation Management" and "Delete This Conversation" buttons at conversation top)
  • Entry Files: src/index.ts (host) + src/client/index.ts (client, exports dsh-session-manager/client)

Use Cases

When you run many sessions daily in DSH Web and the sidebar list keeps growing without native "delete session" entry, this plugin lets you reclaim space, recover accidentally deleted sessions, mark sessions unread for later continuation, and open log directories anytime to troubleshoot. If you also care about token usage and context compaction strategy, it provides a global threshold without needing to modify each Agent preset individually.

Prerequisites & Compatibility

DependencyMinimum VersionNotes
DSH>= 0.1.0-rc.6Depends on settings.section / settings.general.item / conversation.session.header.utilities slots, plus ctx.sessionPersistence / ctx.workspaceRegistry / ctx.agents / ctx.storageDomain / ctx.agentPresets services
Node^22.19.0 或 >=24.0.0package.json#engines declaration
PlatformmacOS / Windows / LinuxOpens log directory in system file manager via open/explorer/xdg-open
Native ModulesNoneHost side only uses Node built-in modules (fs/path/child_process), client side has no native dependencies

Installation

dsh plugin --profile web add github:dream12347/dsh-session-manager

Configuration Options

ConfigTypeDescriptionDefault
Context Compaction ThresholdNumber (17–90)Auto-compact when session context usage reaches the set proportion of model window (1M tokens); retain recent 16% of original text; applies uniformly to all Agent presets80 (i.e., 0.8)
Trash CapacityNumberKeep most recent N deleted sessions, earliest entries auto-purge permanently (unrecoverable) when limit exceeded10

The two settings' visible UI entries are "Settings → General Settings → Context Compaction Threshold" (slider 17%–90%) and "Settings → Session Management → Trash" collapsible section. This plugin has no traditional external config file.

FAQ

Q: What needs to be done after installation?

A: You must restart dsh web after installation. Host plugin and client bundle both load at DSH startup; without restart, new features won't appear.

Q: Can I delete a running session?

A: No. Delete button is disabled on running sessions, and host side will reject the request and return session-live. Currently open but idle sessions (not thinking) can be deleted normally. For multi-tab scenarios, first confirm the session has stopped in all tabs.

Q: How many items can the trash hold? What happens when it's full?

A: Maximum 10 items. When deleting a new session, the earliest item in trash gets auto-purged permanently (including session directory on disk), making it unrecoverable. Important sessions should be restored promptly from trash.

Q: What if a subagent session gets deleted?

A: Even if the main session is deleted, orphaned subagent sessions can be directly cleaned up in the session management panel, provided they're not running. This prevents accumulation of un-cleanable residual sessions.

Q: Where is the "Context Compaction Threshold" config stored? Does it persist after restart?

A: The value persists in DSH storage domain dsh_delete_session (~/.dsh/storages/dsh_delete_session.json). If the default Agent preset is a user preset, it syncs to the corresponding agent.cordis.yml's compaction-basic config; system preset files are read-only and won't be modified. Every agent/pre-step hook applies the threshold to all preset compaction engines, so saving takes effect immediately and persists after restart.

Q: What's the difference between unread marking and official unread?

A: Official unread is amber (waiting for input) and green (completion notice) dots; clicking them "reads in place"—no page navigation, just clears the official reminder. This plugin's blue unread is manual marking, stored in browser localStorage's dsh.session-unread.v1 (shared with other session management plugins). Click empty space to mark unread, click blue dot to clear unread, opening the session auto-marks as read.

Q: Will the sidebar's blue unread dot always be accurate?

A: Official sidebar row elements don't carry session ID attributes; this plugin matches by title text and injects blue dots via MutationObserver. Inside the session management drawer, marking is precise by real session ID, unaffected. Sessions with duplicate titles share the same blue dot in the sidebar—this is a known corner case.

Difficulty Level

Beginner — One command to install, restart DSH, then ready to use. No documentation reading or config file modifications needed. The only "configuration" is the compaction threshold slider in General Settings.

Known Issues & Limitations

  • Cannot delete sessions that are thinking; in multi-tab scenarios, if another tab has the same session open, stop it there first (src/index.ts:414-417)
  • Sidebar unread dots match by title text; sessions with duplicate titles share the same blue dot in sidebar, session management drawer unaffected (README.md:121)
  • After deleting live sessions (opened in current process), memory state is completely cleared by DSH on restart; this is DSH's own behavior, not handled by this plugin (README.md:120)
  • Host side directly writes to registry.state private field to keep WorkspaceRegistry cache in sync with storage domain; both README and source comments mark this as fragile to DSH upgrades, requiring sync adaptation after DSH upgrades (src/index.ts:276-289)
  • Permanently deleted session IDs remain in browser localStorage (preventing "resurrection" on refresh after live session deletion) and in archive collection (harmless residual, not displayed) (README.md:120)
  • Must restart dsh web after installation, otherwise host plugin and client bundle won't take effect (README.md:50)
  • Compaction threshold minimum of 17% is determined by the hard constraint "threshold must be greater than engine's retention ratio of 16%" (src/index.ts:697-699 / src/client/index.ts:2235-2236)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/dream12347/dsh-session-manager)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory