English | 中文
dsh-project-session-store
DSH (DeepSeek Harness) plugin: keep each project's session logs inside the project directory, instead of everything centralized under ~/.dsh/sessions.
By default DSH stores every session under ~/.dsh/sessions/<project-key>/<session-id>/session.jsonl.zstd. This plugin replaces the built-in JSONL persistence backend so session data lives with the project:
<project>/.dsh/sessions/<session-id>/session.jsonl.zstd
Clone a repo, archive it, or move it to another machine — the conversation history travels with the project.
What it does
| Concern | Behavior |
|---|
| Storage layout | <cwd>/.dsh/sessions/<session-id>/session.jsonl.zstd (same file format, same zstd frames — fully compatible readers) |
| Built-in backend | @deepseek-ai/dsh-session-persistence-jsonl is disabled in the composition tree; this plugin provides ctx.sessionPersistence instead |
| Legacy data | On first startup, sessions already under ~/.dsh/sessions are migrated once into their project's .dsh/sessions/ (keyed by each log's header cwd) |
| Unmovable sessions | Sessions whose cwd is gone, sessions without a cwd, and log files whose project directory is not writable stay in place under ~/.dsh/sessions and remain readable/resumable |
| Lookup index | A small pointer file ~/.dsh/sessions/index.json maps session-id -> project dir so resume-by-id and the cross-project Web session list keep working; it contains pointers only, never session data |
| Web UI | Session list still shows all projects grouped by project directory (it merges project-local plus any unmigrated leftovers) |
No cwd sessions | Stay under ~/.dsh/sessions/_no-cwd/, exactly like the stock backend |
Installation
dsh plugin --profile web add @yangzhe1991/dsh-project-session-store
Then restart dsh web (restarting is required — the composition tree changes).
Dev-mode install (local checkout):
# in ~/.dsh/profiles/web
# package.json dependencies:
# "@yangzhe1991/dsh-project-session-store": "link:/absolute/path/to/dsh-project-session-store"
pnpm install
Notes & caveats
- Restart to activate. The plugin swaps the persistence row of the composition tree (
session-persistence-jsonl gets disabled: true), applied at boot.
- One-time migration is best-effort and idempotent. Failures are logged and the leftover stays in the old location. A later startup retries it.
- Uninstall / rollback: remove the plugin from the profile (or set
session-persistence-project-local: disabled: true and re-enable session-persistence-jsonl in cordis.patch.yml). Project-local sessions are then not visible to the stock backend — they live in the project. Either migrate them back manually or keep using this plugin.
- Cross-machine copy: when the project directory (including
.dsh/sessions/) is moved to another machine, copied sessions are discovered (listed) and remain fully readable/resumable — the plugin resolves them by where the files actually live, not by the header cwd (which points at the source machine's path, unresolvable here). After a resume, new events are written back into that same physical file, so the log never splits. The exposed cwd is normalized to the session's real project directory on this machine, and ungrouped sessions are automatically attached to the matching (or auto-created) web workspace via the stock WorkspaceRegistry API — zero configuration, no hard-coded path mappings; anyone copying a project to any machine gets sidebar grouping out of the box.
- The
~/.dsh/sessions/index.json pointer file is irreplaceable-by-scan only for cross-project discovery: if it is deleted, the next session.list rebuilds it by scanning the old root, but project-local dirs outside the index are then only discoverable per-project.
- Version coupling: the plugin does not install official packages itself — the
@deepseek-ai/* packages are peer dependencies resolved from the host's module fallback directory ($DSH_HOME/profiles/node_modules, maintained by the harness, versioned with the host). This isolates it from mixed-install version mismatch (e.g. an old self-installed dsh-session meeting a newer dsh-llm breaking startup). No plugin change needed after a host upgrade unless official APIs change.
Configuration
The plugin row accepts these options (all optional):
- id: session-persistence-project-local
name: '@yangzhe1991/dsh-project-session-store'
config:
# Central root: legacy fallback + pointer index location. Default: $DSH_HOME/sessions
# root: /your/custom/root
# Directory inside each project. Default: .dsh/sessions
# projectDirName: .dsh/sessions
How it works
- Subclasses the official
JsonlSessionPersistence, reusing its coordinator, zstd encoding, crash repair (torn-tail), and durability guarantees — only path resolution, listing, and discovery are overridden.
- Write path:
<cwd>/.dsh/sessions/<id>/session.jsonl.zstd (sessions without cwd fall back to the central _no-cwd/).
- Read path (
findLog by id): pointer index first, then a legacy-root scan fallback; the physical location hit is remembered in-memory so follow-up appends never split the log.
- One-time migration: moves each legacy log into its project dir (same filesystem
rename, EXDEV fallback copy+unlink), updates the index, and prunes emptied legacy directories.
License
MIT
