dsh-session-cleaner
A DeepSeek Harness (DSH) plugin — host half and Web client half in one bundle — that adds two
things to the DSH Web GUI:
- Delete a conversation from the sidebar session menu, with a confirmation dialog.
- Quote / Ask from the right-click menu — select text in a chat message, then right-click. The
plugin takes over the context menu and shows Copy / Quote / Ask, with Copy first, exactly where
the native menu item used to be:
- Copy writes the selection to the clipboard (the same action as before, now drawn by us).
- Quote inserts a Markdown quote block (role + turn metadata) into the composer.
- Ask sends the selection plus your question to a concurrent subagent and streams the answer
into the right sidebar, without interrupting the main conversation.
中文说明
Features
| Surface | What it does |
|---|
sidebar.workspaces.session.menu.item | Delete session — stops a running session (flush + detach), detaches it from the workspace registry, invalidates its projection cache, physically removes the session directory, cleans its spill directory, cascades to its origin: subagent children (fork branches are never cascaded), then broadcasts api-session/removed. |
shell.overlay | Selection right-click menu: Copy (clipboard) / Quote (insert into the composer) / Ask (concurrent subagent question). The menu is drawn by the plugin because the desktop app builds its native context menu in the Electron main process, which a renderer plugin cannot extend; preventDefault() on contextmenu keeps the native menu from popping. |
sidebar.right.pane.tab | Follow-up tab: streams the ask subagent's answer (reasoning + text) in the right sidebar. |
Ask reuses one subagent
Every question does not spawn a new subagent. The plugin keeps a single continuable subagent
labelled ask per parent session and delivers the next question to it (discovering the existing one
through the official subagents.listChildren() catalog, so it survives a host restart).
Scoped auto-compaction for the ask subagent
Because the reused ask subagent's context grows with every question, the host registers its own
agent/pre-step listener that calls ctx.compaction.compactIfNeeded(agent, "pressure", signal)
only for this plugin's own ask subagents. Global automatic compaction stays off
(compaction-basic is mounted with auto: false) — the main conversation is unaffected.
Install
The plugin is a normal DSH bundle. Add it to your profile's package.json:
{
"dependencies": {
"@local/dsh-session-cleaner-host": "link:/absolute/path/to/dsh-session-cleaner-host"
},
"dsh": {
"profile": {
"bundles": [
// …
"@local/dsh-session-cleaner-host"
]
}
}
}
The package name must be used consistently in three places:
package.json → nameclient.js → window.__ModuleLoader__.load({ id: "…" })- the profile's
dsh.profile.bundles entry
Then add the compaction backend to your profile patch layer
(~/.dsh/profiles/<profile>/cordis.patch.yml), which is applied after every bundle layer:
# Compaction backend for the ask subagent's scoped auto-compaction.
# `auto: false` keeps GLOBAL automatic compaction off; the plugin calls
# ctx.compaction.compactIfNeeded() itself, scoped to its own ask subagents.
- id: compaction-basic
name: "@deepseek-ai/dsh-compaction-basic"
disabled: false
config:
auto: false
Keep this row in the profile patch, not in this package's bundle patch: installing a plugin
must not silently enable another package for the whole profile.
Restart DSH after changing host-side code, then reload the page. Verify which build is live:
curl -s http://127.0.0.1:19387/api/dsh-session-cleaner/version
# {"ok":true,"name":"dsh-session-cleaner","build":"…","features":{…}}
Usage
Quote / Ask
- Select some text in a chat message.
- Right-click inside the selection.
- The context menu opens with Copy / Quote / Ask (Copy first, then a separator).
- Quote appends a quoted block to the composer. Ask swaps the menu for a question box; send it
and the Follow-up tab opens in the right sidebar with the streamed answer.
Right-clicking in the composer, or right-clicking without a selection, keeps the normal system menu
(cut / paste / select all).
Delete a conversation
Sidebar session row → ⋯ → Delete session. Deleting the currently open session stops it and
switches the page to a new session.
HTTP API
All routes are served by the plugin's host half (same-origin, browser cookie auth):
| Method | Path | Body | Purpose |
|---|
GET | /api/dsh-session-cleaner/version | — | Which build is live (diagnostics). |
POST | /api/dsh-session-cleaner/ask | { sessionId, text } | Deliver a question to the reused ask subagent, creating it once if needed. |
POST | /api/dsh-session-cleaner/delete-session | { sessionId } | Delete a whole session (and cascade to its subagent children). |
POST | /api/dsh-session-cleaner/delete-subagent | { childId, parentId } | Delete one direct subagent child. Guarded by a lineage check. |
POST | /api/dsh-session-cleaner/terminate-children | { sessionId } | Drain every continuable descendant of a session. |
Design notes and hard-won constraints
These are the constraints that shape the implementation. Several of them were established by reading
the shipped DSH sources, and getting any of them wrong produces silent data loss.
- DSH exposes no "delete a session" API.
sessions, sessionPersistence,
sessionProjectionCache and sessionController are all append-only; the persistence seam documents
"Nothing deletes session files … the seam has no deletion API." This plugin therefore performs
deliberate on-disk surgery — and compensates with strict identity checks.
- Never rewrite another session's log. The plugin originally rewrote the parent log to drop a
subagent/catalog row. Session logs are append-only and may be written concurrently by the host, so
a read → filter → atomic-rename could truncate a conversation. rewriteParentLog now defaults to
false.
- Session directory lookup is identity-verified. Any candidate directory must yield a log whose
header
id equals the requested session id; the plugin never falls back to guessing.
subagent/catalog is append-only. There is no supported way to remove a row, and removing the
child's session behind a live row produces a dangling entry. The plugin does not touch catalog rows.- Subagent operations are lineage-guarded.
delete-subagent refuses unless
header.parentSession === parentId && header.origin === "subagent", and refuses
childId === parentId — without that check, "delete the subagent" can delete the conversation you
are looking at.
- Compaction needs a live idle agent.
compaction.compactNow(agent, signal) takes a
ManualCompactAgentContext (it needs runMaintenance()), but a continuable subagent is not
resident after its turn settles. There is therefore no supported way to compact a finished
subagent on demand; compaction only works at agent/pre-step, while the turn is open and the agent
is alive. That is why the plugin hooks agent/pre-step instead of offering a button.
- Self-contained by design. The host half imports only Node builtins — no
@deepseek-ai/*
runtime dependency, so the plugin cannot shadow the official packages in a profile's
node_modules. package.json declares no dependencies at all.
- Selections are quoted verbatim and capped at 2000 characters; a selection spanning two messages
or inside a streaming message is ignored.
Tests
npm test
Two self-contained suites, no DSH, no browser and no real session data:
| Suite | Covers |
|---|
test/internals.test.mjs | host half: zstd session-log framing, projection keys, log decode/encode |
test/client-context-menu.test.mjs | client half: loads the real client.js through a minimal DOM/React/ctx stub, then checks the right-click path — capture-phase listener, preventDefault() only on a selected message, menu order (Copy → Quote → Ask), viewport clamping, native-menu passthrough in the composer / without a selection, and listener cleanup on dispose |
test/verify-served-bundle.mjs is an optional live check (needs a running DSH): it recomputes the
host's bundle rev from client.js metadata, fetches the exact bundle the host is serving, and fails if
the running host still hands out a stale copy. Point it at another instance with DSH_WEB_URL.
Compatibility
Developed and tested against DSH 0.2.0-rc.2 (the desktop/Web profile: @deepseek-ai/dsh-base +
@deepseek-ai/dsh-web-app). It relies on public seams — slots, locale, sessions, subagents,
agents, sessionPersistence, sessionProjectionCache, workspaceRegistry, spillStore,
compaction — and degrades gracefully when an optional service is missing.
License
MIT — see LICENSE.
