dsh-session-artifacts
This package is built by DeepSeek-v4.1 flash!
English · 中文
Clean up what a session left in your workspace — and, when you want it,
delete the session record too. Opt-in, previewed, and verified before anything
is removed.
A session's scripts, reports and generated files stay behind after the
conversation is gone. Nothing in DSH records which files those were, so this
plugin reconstructs that from the session log and shows you the exact list —
with the total size — before anything is deleted.
Three things it can do, chosen by two checkboxes in one dialog:
- Delete the artifacts, keep the conversation — tidy up a session's mess
without losing the session.
- Delete the session record — with or without its artifacts.
- Neither is assumed: the artifact step is off by default.
It is self-contained: it removes the session record itself and does not call
dsh-chat-manager's /plugins/dsh-session-delete route, so it keeps working
when that plugin is disabled or absent.
What it does
- Open the session's ⋯ menu and pick Delete session and artifacts…
- The dialog shows the exact file list and total size before you commit.
- Tick what you want removed. At least one box must be ticked.
- Confirm. When the record is being removed it goes first, then the previewed
files.
- If a file could not be removed, the dialog offers Retry the files left
behind — it retries exactly those paths, not the whole preview.
The artifacts-only mode needs no session deletion at all: the Host holds the
previewed list behind a nonce, so the files are removable while the session and
its log stay exactly where they are.
Deleting the session record
The persistence seam deliberately has no deletion API — its own contract
states that logs accumulate under the session root until removed externally. So
this plugin performs the removal itself, against the fixed layout:
<sessionRoot>/<project>/<sessionId>/session[.vN].jsonl[.zstd]
The location is resolved through the persistence backend
(resolveCurrentLog), then every component is re-checked before anything is
touched:
- exactly three segments under the root, with a session-log leaf name;
- each directory is a real directory and the log a real file — no symlinks;
- nothing resolves outside the root;
- removal is a two-step quarantine: the directory is renamed into a sibling
temp directory, its identity is re-verified there, and only then deleted. A
failure part-way restores the original rather than leaving it half-deleted.
Stopping a session that is open
An open session is live in the host registries even when nothing is running
in it, so its log writer is still attached and its row would reappear in the
sidebar. It has to be torn down before its storage can go — and the registry
exposes no dispose.
The only supported teardown is the AgentHandle returned to whoever created
the Agent, so this plugin keeps its own handle tracker: it observes Agent
creation on the shared agents service and retains each handle. Deletion then:
- cancels a running turn (the same path the Stop button uses);
- disposes the Agent through its handle — this is what unregisters it and
detaches its Session;
- waits for both registries to drain, then removes the storage.
The tracker is this plugin's own rather than another plugin's, so the capability
does not go away when that plugin does.
One case cannot be handled: an Agent that was already live before the
plugin loaded has no captured handle (the handle was only ever given to its
creator). That deletion is refused with a message telling you to restart DSH —
after a restart the plugin sees every Agent from the start. It is refused rather
than deleted underneath its writer, because reporting a deletion that did not
happen is worse than not deleting.
How a file is attributed to a session
The durable session log is the only authoritative record of what a session
touched, so attribution is read from it:
| Evidence | Meaning | Deletable |
|---|
write result with meta.operation: "create" | the session materialized the file | yes |
| shell command window + file creation time | the file was created while a command ran | yes, if unique |
present call | the session delivered the file | no (reported only) |
write result with meta.operation: "update" | the session rewrote a file that already existed | no |
edit call | the session only rewrote an existing file | no |
Rewriting a file you already owned never makes it disposable, so update and
edit results are reported but never offered. A failed tool call
(FS_SANDBOX_DENIED, FS_NOT_OBSERVED, FS_STALE_VERSION, …) contributes
nothing, because the tool never materialized anything.
present is delivery, not authorship: a session asked to hand you a paper
you already had would otherwise make that paper deletable. Delivered-only files
are counted in the dialog and left alone. Set includeDelivered: true to opt
into the older, more aggressive behavior.
Shell-created files
File-tool writes are recorded explicitly. Shell commands are not: a pwsh call
records only its command text, and its tool/result carries no meta at all,
so nothing durable names the files a python foo.py run produced. In practice
this is the dominant source of leftovers — a session that writes twenty
scripts through the shell produces twenty artifacts that a file-tool-only
reader never sees.
The remaining evidence is creation time. On NTFS birthtime is a real
creation timestamp, distinct from mtime, and it survives later edits — so it
answers "was this file created while this command was running?". Pairing each
shell tool/call with its tool/result gives a tight window per command.
Three rules keep this safe:
- Tight windows. Only the interval a command actually ran counts. A
whole-session window is unusable: a session that ran two commands and then
spent twenty minutes browsing would otherwise claim every file created during
its lifetime. (Measured on a real log: such a session had 90 files inside its
session-wide span and 0 inside its actual command windows.)
- Uniqueness. A file created inside two sessions' windows is attributed to
neither, because a wrong attribution deletes something this session never
made. Concurrent sessions therefore reduce the result instead of corrupting
it.
- Fail closed. If the sibling sessions cannot be enumerated, the pass
claims nothing and says so in the dialog. "Only my window covers it" cannot
be established without knowing the others.
Only creation is claimed. A file that merely changed during a window was not
produced by the session and is left alone. Inferred files are labelled
命令行 / shell in the list, since they rest on weaker evidence than a
recorded write.
Safety
- Workspace fence. A session may only ever propose files inside its own
recorded working directory.
- DSH home fence. Nothing under
~/.dsh is ever an artifact, whatever the
session's working directory is. The workspace fence alone is relative to
cwd, so a session opened at ~ or C:\ could otherwise reach the
installed plugins, the built skills, the profiles, and the credential store.
A genuine workspace nested inside the home (e.g. ~/.dsh/scratch) still owns
its own files, but cannot reach its neighbours.
- Package fence. A file inside a directory that is a DSH package — it holds
SKILL.md, cordis.patch.yml, cordis.yml, or a package.json with a
dsh/cordis block — is not offered, so a plugin or skill the session built
inside its own workspace survives. Set protectPackages: false to disable.
- Symlinks. A candidate whose real path escapes the workspace through a
symlink is skipped, both at preview and at removal time.
- No stale deletions. Every file is re-checked immediately before it is
unlinked; a file whose size or identity changed since the preview is skipped
rather than removed.
- Relative paths resolve against the session's cwd, never the Host process
working directory, so
report.md means the file the session actually wrote.
- The client never names paths. The Host holds the previewed set behind a
single-use, 10-minute nonce. A path the user was never shown cannot be
deleted, and a nonce cannot be replayed.
- Retry is pinned. A retry entry re-baselines the file's size (the preview
size is stale by definition) but pins its device + file index, so a path
swapped for a different file between the two passes is refused.
- Directories are never deleted as artifacts. Only regular files are
offered; directories the deletion empties are pruned, stopping at the
workspace root.
- No secure erasure. Removal is an ordinary unlink. Backups, cloud copies,
snapshots, and filesystem-level recovery are outside its scope.
Configuration
All fields are optional; the defaults are the safe ones.
| Field | Default | Meaning |
|---|
dshHome | derived | Overrides the DSH home used by the home fence. Otherwise DSH_HOME, otherwise the parent of a <home>/sessions store. |
extraExcludes | [] | Extra absolute paths that must never be offered. |
protectPackages | true | Refuse files inside a DSH plugin/skill package. |
includeDelivered | false | Also offer files the session merely delivered. |
includeShell | true | Run the shell creation-window pass. |
shellSlackMs | 5000 | Slack around a command window, absorbing the gap between the event clock and the filesystem clock. |
deleteSession | true | Whether the Host offers session-record deletion. false makes the plugin artifacts-only: the record checkbox is hidden and the flow never touches the log. |
lifecycleTimeoutMs | 20000 | How long to wait for a stopped session to leave the live registries. |
Requirements
- The per-session JSONL session-persistence backend (
sessionPersistence),
which every shipped composition mounts.
- The live Agent registry (
agents), provided by @deepseek-ai/dsh-agent. It
is a declared dependency, because the handle tracker must be installed
before any Agent is created — a tracker installed later captures nothing.
- DSH core
0.2.x for the session-menu and overlay slots it extends.
No other plugin is required.
sessions is used when present, to stop a running turn before teardown.
Limitations
- Shell attribution relies on
birthtime. On a filesystem that does not record
a true creation time, the shell pass finds nothing rather than guessing.
- Only the creating session is detected. A file one session created and
another later edited stays attributed to the creator.
- A session that creates a file through a long-running background job started
near the end of its window may fall outside the window. Prefer the file tools
for anything you expect to delete later.
- Directories are never offered, so a session that only created directories
(and nothing inside them) leaves them behind.
- The preview is a snapshot. Files created after it are not included.
- Subagent sessions record their own writes; deleting a parent does not
automatically delete a child's artifacts.
- A session that was already open before this plugin loaded cannot be torn
down (no handle was captured), so its record cannot be deleted until DSH is
restarted. Deleting its artifacts still works.
- The handle tracker observes the shared
agents service, so it only sees
Agents created through it. A composition that creates Agents some other way
behaves like the pre-existing case above.
Install
dsh plugin --profile <profile> add dsh-session-artifacts
Or from a checkout:
dsh plugin --profile <profile> add <path-to-this-directory>
Then restart DSH for the Host and client halves to compose.
Uninstall
dsh plugin --profile <profile> remove dsh-session-artifacts
Uninstalling removes only this plugin. It never deletes sessions or artifacts
on its own.
Tests
npm test
The suites cover attribution rules, the shell creation-window pass (including
the fail-closed path and the two-session ambiguity rule), the workspace / DSH
home / package fences, cross-drive paths, symlink escapes, identity
re-verification, relative-path resolution, empty-directory pruning, nonce
single-use, the retry nonce, the request fence, and the real apply() wiring
end to end.
License
MIT
