dsh-desktop-archive-manager

dsh-desktop-archive-manager

English | 中文

Manage the archived Sessions of DeepSeek Harness: browse them, restore them, and delete them permanently — the surface the harness itself does not ship. Written for the desktop app, and it works in any web-capable profile.

The harness archives Sessions but never deletes them. The shipped ui-workspace package states the limit outright: "No Session deletion — sessions can be archived but never deleted." This plugin fills that gap without patching the harness core — it works on a stock install.

Requirements: the DeepSeek Harness Desktop app (developed against 0.2.0-rc.2), or any Harness profile with a web UI. The bundle row carries no disabled gate — it activates in every profile, and the web surface (host route plus browser half) simply stays quiet where no webserver runs.

How it differs from the existing session-archive-manager: that plugin adds workspace.deleteSession by patching the harness core and therefore needs a source checkout or a forked build. This one adds no core API: its host half removes the stored artifacts itself, so it installs into the shipped desktop app as-is.

---

1. Install and uninstall

From the app: Settings → Plugins → Local plugins

Install the companion dsh-local-plugin-source once and the local plugin folder (%USERPROFILE%\.dsh\local-plugins) becomes an in-app source:

From a package spec

The sidebar Plugins → Add plugin dialog accepts a package name, a git URL, a tarball, or a local absolute path:

dsh plugin add dsh-desktop-archive-manager                 # after publishing to npm
dsh plugin add github:<you>/dsh-desktop-archive-manager    # straight from GitHub
dsh plugin add C:\path\to\dsh-desktop-archive-manager      # local folder

Any of these goes through the profile's own installer: pnpm add <spec> → validate dsh.bundle.patch → append the package name to dsh.profile.bundles in the profile's package.json → recompose and activate (no restart).

Uninstall

Remove the bundle from the Plugins page (or dsh plugin remove dsh-desktop-archive-manager): the bundle selection is dropped, the Loader row is unloaded, and pnpm removes the package. The plugin keeps no global state, so nothing is left behind — except the Sessions it deleted.

2. What you get in the UI

Localized in English and Simplified Chinese (locale namespace archive-manager).

3. What a deletion actually removes

Per Session, the host half touches exactly three things:

1. The Session log directory — <root>/<project directory>/<sessionId>/, including every stored format generation (session.v4.jsonl.zstd, .v3, .v2, …). The path comes from the persistence backend's own locate(); when a backend cannot answer, the plugin falls back to scanning <root>/*/<sessionId>/.
2. The projection-cache record — that Session's row in the session_projcache domain, deleted through the domain API (ctx.storageDomain), never by writing the JSON file behind its back.
3. The archive mark — removed from archivedSessionIds in workspace.json, which also refreshes the sidebar.

Nothing else is touched: project directories, other Sessions, attachments and workspace records stay as they are.

Safety gates

• only Session ids that are currently archived are accepted — anything else is refused with archive-manager/not-archived;
• a Session id must be one safe path segment (regex-checked, .. refused), so path traversal is impossible;
• a Session with running work is refused (workspace/session-activity plus a live-Agent status check);
• the API is one exact route with a same-origin check (Origin header + a custom request header); it never touches the /api trust boundary.

4. Sessions that are still live in memory

A Session may have been created or opened during the current run, so the process still holds it (Agent/Session in memory, write handle claimed). Removing the files works, but the row cannot disappear yet — and unarchiving it could wake a Session with no log.

At every startup the plugin runs one prune: archive marks whose Session is neither stored on disk nor live in the process are dropped, so whatever a live Session left behind disappears by itself on the next start.

5. Package layout

dsh-desktop-archive-manager/
├── package.json          # dsh.bundle.patch + dsh.client (both halves in one package)
├── cordis.patch.yml      # bundle patch: inserts the desktop-archive-manager row (no disabled gate)
├── lib/host.js           # host half: the Cordis plugin and POST /archive-manager/api
├── lib/client.js         # browser half: a prebuilt __ModuleLoader__ bundle
├── lib/core.js           # dependency-free deletion core (unit-tested)
├── test/*.test.mjs       # node --test suite (38 tests)
├── LICENSE
└── README.md / README.zh.md

The two declarations that make it a plugin:

"dsh": {
  "bundle": { "patch": "./cordis.patch.yml" },
  "client": { "platform": "web", "inject": [], "external": [] }
}

• dsh.bundle.patch makes the package a bundle: the installer lists it in dsh.profile.bundles and inserts its rows.
• dsh.client (with exports["./client"]) gives the same row a browser half: client-modules scans enabled Loader entries, finds the declaration on this package, and serves lib/client.js. Host and browser halves therefore come from one package and one version.

6. Host endpoint

One exact route: POST /archive-manager/api, JSON body, responses shaped { ok: true, value } or { ok: false, error: { code, message, details } }.

7. Notes for contributors

• An inject face's hooks object is flattened by the renderer. inject: () => ({ hooks: { archives } }) reaches the component as the selector hook useArchives (see bindInjectSources in ui-renderer); the hooks key itself is dropped. Reading props.hooks.archives throws during render and the slot error boundary marks the entry abdicated — the seat then silently disappears. Name custom sources so they cannot shadow the owner's standard hooks (this plugin uses archiveWorkspaces / archiveSessions because seats like shell.overlay and main already carry useWorkspaces / useSessions).
• The browser half is a prebuilt bundle with no bundler step at install time. It may only require modules from the platform seed table (react, react/jsx-runtime, react-dom, @deepseek-ai/cordis, @deepseek-ai/dsh-client-store, @deepseek-ai/dsh-client-ui-slots, @deepseek-ai/dsh-client-ui-primitives, @deepseek-ai/dsh-client-ui-dockkit).
• The host half injects the web surface optionally (export const inject = [] plus ctx.inject([...], cb)), so the row still activates where there is no webserver instead of waiting forever.

8. Tests

node --test "test/*.test.mjs"

38 tests cover the deletion core (path traversal, only the target Session removed, sibling directories kept), the host half (cold delete, live policy, the three prune judgements, request gates, partial batch failures) and the browser half (slot registrations, host-call plumbing, failure and "pending restart" notices, restore) — including render tests that project each registration through the renderer's real hook flattening before rendering the component, which is what caught the inject-face contract bug described above.

9. Known limitations

• A live Session's row waits for a restart. The harness exposes no public "release Agent/Session by id", and this plugin does not reach into another plugin's fibers; after a restart the process no longer holds it, the row goes away, and prune clears the mark.
• Only the Session itself is deleted — subagent Sessions it spawned are separate Sessions and are left alone.
• Content indexes are out of scope. This profile's Session search index is :memory: (openAt: never); a deployment with an on-disk index rebuilds it after a restart, and the plugin never touches it directly.
• Deletion is irreversible. The UI therefore requires an explicit acknowledgement and lists every log directory in the dialog.