dsh-session-manager 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +247 -218
  2. package/README.md +139 -158
  3. package/README.zh.md +137 -166
  4. package/lib/annotation-store.js +41 -1
  5. package/lib/client.js +2772 -1953
  6. package/lib/index.js +134 -2
  7. package/lib/session-files.js +15 -2
  8. package/package.json +2 -2
package/README.md CHANGED
@@ -1,158 +1,139 @@
1
- # dsh-session-manager — session manager for DeepSeek Harness
2
-
3
- English | [中文](README.zh.md)
4
-
5
- [![npm version](https://img.shields.io/npm/v/dsh-session-manager)](https://www.npmjs.com/package/dsh-session-manager)
6
- [![GitHub](https://img.shields.io/badge/GitHub-repository-blue)](https://github.com/hkkz9522/dsh-session-manager)
7
- [![CI](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml)
8
- [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
9
-
10
- DSH Web session manager: delete, archive, move across workspaces, migrate preset; favorites, review-later, search, sort, priority, add tags and notes (manual / semi-automated). Suggestions are welcome on GitHub.
11
-
12
- ## Features
13
-
14
- ### Session lifecycle
15
-
16
- - **Archive / unarchive** sessions.
17
- - **Delete sessions** with an explicit irreversible-action confirmation. Deletion is rejected for subagent sessions and transient blank placeholders.
18
- - **Move to workspace**: preserves history, title, archive state, and derived-session relationships, and rewrites the session's working directory (`cwd`) to the target workspace. The move updates the live writer's header in place so any pending tool calls keep landing on the new path.
19
- - **Migrate Agent preset**: change the preset on demand. Typical use case: when the original preset was renamed or removed and the session can no longer resume, you can repair that session. The migration rewrites the latest `agent-preset/selected` event (or the session header if no such event exists) without altering message history.
20
-
21
- ### Session manager panel (sidebar)
22
-
23
- - Browse active and archived sessions, switch workspaces, and filter, sort, search across the list.
24
- - Open a session directly from a row, or click a tag chip to filter the list to that tag.
25
- - Per-row actions: **Open**, **Archive / Unarchive**, **Move**, **Migrate preset**, **Delete**.
26
- - Each popup dialog (Move / Migrate preset / Delete / the panel itself) toggles closed when its trigger is clicked a second time, matching the built-in title-area buttons.
27
-
28
- ### Search, filters, and sorting
29
-
30
- - Case-insensitive title and session-ID search; whitespace is trimmed. Message history is never read.
31
- - Combine a workspace selector (All / Ungrouped / specific) with the archive filter (All / Active / Archived).
32
- - Combine favorite/review flags, tag and priority filters; sort by recently updated (default), least recently updated, newest created, oldest created, or **priority (1 → 5)**.
33
- - See matching/total counts and reset all view controls together. These controls only affect the manager panel — workspace membership, archive state, and the native sidebar ordering are untouched.
34
- - Failed workspace loads can be retried without losing search, sort state.
35
-
36
- ### Favorites, review flags, tags, notes and priority
37
-
38
- - Favorite / Review / **Tags/Notes** / priority controls are reachable from both the **title bar** (current session) and the **manager panel** (every row).
39
- - Favorites and review flags are manual — independent of archive / running state, never cleared automatically.
40
- - Priority is a dropdown **1 Highest, 2 High, 3 Normal, 4 Low, 5 Lowest** with **3 (Normal) as the default**; the manager row and title bar always show a P1–P5 badge. Legacy `null` priorities are normalized to 3.
41
- - Tags: up to 20 per session, 32 characters each. Both English `,` and Chinese `，` are separators, whitespace is trimmed, duplicates are merged case-insensitively.
42
- - Notes: plain multiline text, up to 2000 characters.
43
- - Tags, notes and the AI **paste** textarea all share the same `sm-noteInput` style and `rows: 3` height (60px min-height), so the three input boxes line up visually.
44
- - The "Tags/Notes" editor also surfaces **Copy Prompt** / **Import** controls for AI-assisted tagging (see below).
45
- - Annotations are stored as plain text in `dsh-session-manager/annotations.v1.json` under the DSH home, keyed by session ID. They do not rewrite history or enter model context automatically. Move / Migrate preserve them; Delete cleans them up (and reports cleanup failures separately).
46
- - Both UI surfaces share live state. Same-origin browser tabs receive change notifications via `BroadcastChannel`; refocusing or reopening the manager refreshes data.
47
- - Saves are atomic, use a cross-process lock, and never silently overwrite another editor: revision conflicts surface a "load latest" prompt. Unsaved drafts survive a save failure.
48
- - A crash-left `annotations.v1.lock` is not forcibly removed; verify no writer is active before handling it.
49
-
50
- ### AI-assisted tagging (manual, opt-in)
51
-
52
- The **Tags/Notes** editor has two extra buttons above the paste box. Neither calls a model automatically — both keep you in control:
53
-
54
- - **复制 Prompt** / **Copy Prompt** copies a structured prompt (Chinese or English, matched to the active UI language) to the clipboard. Paste it into the current conversation to ask the model to generate tags / note / priority within the plugin's limits.
55
- - **导入** / **Import** reads the clipboard, extracts the first JSON object (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates it against the same limits, and populates the editor fields. Oversized notes are truncated; invalid tags / priority are dropped with reasons. Importing into a dirty draft asks for confirmation first. If parsing still fails, the error message includes the actual `JSON.parse` position from each recovery attempt so you can see exactly which character broke it.
56
-
57
- The prompt templates and import parser live in `lib/clipboard-parser.js` and are bundled into the client; no build step or network call is required.
58
-
59
- ### Current session title bar
60
-
61
- The right side of the title area offers:
62
-
63
- - **Archive / Unarchive** the current session.
64
- - **Move to workspace** with a workspace picker.
65
- - A red **Delete session** button with confirmation.
66
-
67
- The same buttons appear in the manager row.
68
- ## Agent preset migration
69
-
70
- Use this when a session can no longer resume because its original preset no longer exists, for example after removing a custom preset such as `router-standard`.
71
-
72
- 1. Open **Session manager**.
73
- 2. Locate the session and select **Migrate preset**.
74
- 3. Choose one of the currently available target presets and confirm.
75
-
76
- The plugin determines the session's effective preset from its latest `agent-preset/selected` event when present; otherwise it uses the session header. It then rewrites that event in place (or appends a fresh one if the session has never recorded a selection), so the migration is durable and the prior entry remains visible in the event log as history. For a live session, the new event is appended in memory via `Session.append()` and flushed to disk via `SessionStore.flush()`; the api-gateway's chat panel sees the new preset on the next event fold.
77
-
78
- > A preset migration changes session metadata only. It does not alter message history, files, or the selected workspace.
79
-
80
- ## Install
81
-
82
- The plugin is listed in [dsh-market](https://github.com/dsh-market/dsh-market) and [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin), and can be installed directly from the **Plugin Marketplace** inside DSH.
83
-
84
- ### From dsh-market
85
-
86
- ```powershell
87
- dsh plugin --profile web add npm:dsh-session-manager
88
- ```
89
-
90
- ### From GitHub
91
-
92
- ```powershell
93
- dsh plugin --profile web add github:hkkz9522/dsh-session-manager
94
- ```
95
-
96
- Restart DSH Web after installation. If the browser still holds an older client bundle, force refresh with `Ctrl+Shift+R`.
97
-
98
- ### Local development / runtime injection
99
-
100
- ```text
101
- dev_inject_plugin {"dir": "<absolute path to this repository>"}
102
- ```
103
-
104
- ## Safety and behavior
105
-
106
- - **Deletion is permanent**, so the UI always asks for confirmation. The API checks the session ID, directory boundary and artifact header before deletion; traversal, symlinks and junctions are refused.
107
- - Move and preset migration retain the live session/agent; deletion cancels and disposes it. Move updates the stored cwd and the existing live writer's header.
108
- - The management list hides subagent sessions and the move API rejects them. Blank sessions without a persisted artifact cannot be moved.
109
- - Cold rewrites preserve the artifact's stored format rather than forcing a v2 → v3 upgrade. Moves and rewrites refuse corrupt/truncated Zstd logs or JSONL logs with incomplete final lines instead of publishing partial history.
110
- - Preset migration separates backup, publication and rollback. If rollback fails, recovery files are retained and their paths are included in the error; do not remove them.
111
- - Incomplete startup scans skip workspace reconciliation. Complete scans preserve live sessions and membership added during the scan.
112
- - Plugin mutations are serialized per session and request bodies are limited to 64 KiB. This queue supplements, rather than replaces, DSH's persistence coordination.
113
-
114
- ## Compatibility
115
-
116
- | Plugin version | Verified DSH version |
117
- | --- | --- |
118
- | 0.5.1 | v0.1.6-alpha.2 |
119
- | 0.4.11 | v0.1.5-rc.2 |
120
- | 0.4.10 | v0.1.5-rc.1 |
121
- | 0.4.9 | v0.1.5-rc.1 |
122
- | 0.4.7 | v0.1.5-rc.1 |
123
- | 0.4.4 | 0.1.3-alpha.2 |
124
- | 0.4.1 | 0.1.3-alpha.2 |
125
- | 0.4.0 | v0.1.2-rc.1 |
126
- | 0.1.2 | v0.1.0-rc.7 |
127
- | 0.1.1 | v0.1.0-rc.7 |
128
- | 0.1.0 | v0.1.0-rc.7 |
129
-
130
- Requires Node.js 22.15+ (22.x) or 24+ for built-in Zstd support.
131
-
132
- The plugin is a Cordis plugin and declares `cordis: ">=4.0.0-rc <5"` as its peer dependency.
133
-
134
- ## Development
135
-
136
- - `lib/index.js` is the host-side ESM plugin; `lib/client.js` is the Web client bundle. No build step is required.
137
- - Before submitting changes, run:
138
-
139
- ```powershell
140
- npm run check
141
- npm test
142
- npm run check:package
143
- git diff --check
144
- ```
145
-
146
- Tests use isolated temporary directories and the real plugin entry point, never real sessions. CI runs these checks on Windows/Linux with Node 22.15.0/24.
147
-
148
- Optional integration check: run `node scripts/smoke-test.mjs` against a running test instance of DSH Web. This contacts a real service and is not part of the default unit test suite.
149
-
150
- Release history is in [CHANGELOG.md](CHANGELOG.md).
151
-
152
- ## Acknowledgments
153
-
154
- Thanks to everyone who installs and uses dsh-session-manager, and to the people who file issues and open pull requests to help improve it. This plugin is listed in [dsh-market](https://github.com/dsh-market/dsh-market) and [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin). Suggestions and feedback are welcome.
155
-
156
- ## License
157
-
158
- [MIT](LICENSE)
1
+ # dsh-session-manager — session manager for DeepSeek Harness
2
+
3
+ English | [中文](README.zh.md)
4
+
5
+ [![npm version](https://img.shields.io/npm/v/dsh-session-manager)](https://www.npmjs.com/package/dsh-session-manager)
6
+ [![GitHub](https://img.shields.io/badge/GitHub-repository-blue)](https://github.com/hkkz9522/dsh-session-manager)
7
+ [![CI](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml)
8
+ [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
9
+
10
+ ## 0 Overview
11
+
12
+ DSH Web session manager: delete, archive, move across workspaces, migrate preset; favorites, review-later, search, sort, priority, add tags and notes; bulk processing. Suggestions and feedback are welcome on GitHub.
13
+
14
+ ## 1 Features
15
+
16
+ ### 1.1 Session lifecycle management
17
+
18
+ - **Delete** is irreversible and always asks for confirmation. Subagent sessions and transient blank placeholders (no persisted artifact) cannot be deleted.
19
+ - **Archive / Unarchive** moves a session in and out of the active list without touching its disk content.
20
+ - **Move to workspace** keeps history, title, archive state and derived-session relationships intact, rewrites the session's `cwd` to the target workspace, and updates the live writer's header in place so any pending tool calls keep landing on the new path.
21
+ - **Migrate Agent preset** rewrites the latest `agent-preset/selected` event (or the session header if no such event exists) so a session whose preset was renamed or removed can resume. Message history is never altered.
22
+
23
+ ### 1.2 Session shortcuts
24
+
25
+ - **Favorites / Review-later** are manual flags that survive archive and session end; neither is cleared automatically.
26
+ - **Search** matches title, session ID, note and tags case-insensitively, trims whitespace, and never reads chat history.
27
+ - **Filters and sorting** combine a workspace selector (All / Ungrouped / specific) with an archive filter (All / Active / Archived), then layer favorites / review, tag and priority filters on top. Sort by recently updated (default), least recently updated, newest created, oldest created, or **priority (1 → 5)**.
28
+ - **Priority** is a dropdown **1 Highest, 2 High, 3 Normal, 4 Low, 5 Lowest**, default **3 (Normal)**; legacy `null` priorities are normalized to 3.
29
+ - **Tags / Notes**: up to 20 tags per session (≤ 32 characters each) and a 2000-character note. Both English `,` and Chinese `，` are separators, whitespace is trimmed, duplicate tags are merged case-insensitively.
30
+ - **AI-assisted tagging** is manual and opt-in: **Copy Prompt** writes a structured prompt (Chinese or English, matched to the active UI) to the clipboard; **Import** parses the clipboard JSON (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates it against the same limits, and populates the editor fields. Neither button calls a model automatically.
31
+ - Annotations live in plain text under the DSH home (`dsh-session-manager/annotations.v1.json`), keyed by session ID. Same-origin browser tabs stay in sync via `BroadcastChannel`. Saves are durable across crashes; revision conflicts surface a "load latest" prompt.
32
+
33
+ ### 1.3 Bulk management
34
+
35
+ - **Batch process mode**: click the toggle in the panel header to reveal row checkboxes, a **Select all in filter / Clear selection** toolbar pair, and the bulk action bar. Exiting batch process clears the current selection.
36
+ - **Action bar** lists every batch action:
37
+ - **Annotation toggles**: **Archive / Unarchive / Favorite / Unfavorite / Mark for review / Clear review flag**.
38
+ - **Mutating actions**: **Add tags / Clear tags / Set priority / Move to workspace / Migrate preset / Delete session**.
39
+ - **Confirmation flow**:
40
+ - Non-destructive actions (archive / unarchive / favorite / unfavorite / review / unreview / add-tags / clear-tags / set-priority / move / preset-migrate) fire immediately and report per-session results in a **result dialog** with **Success / Failed / Skipped** groups and a one-click **Retry failed** that re-arms the failed IDs into the selection.
41
+ - Destructive actions (**delete session**) first open a **preview dialog** listing the targeted sessions, then show a progress bar, then a per-id result dialog.
42
+
43
+ ## 2 UI entry points
44
+
45
+ ### 2.1 Title bar
46
+
47
+ The right side of the title area exposes actions for the **current session**: **Archive / Unarchive**, **Tags / Notes**, **Move to workspace**, **Delete session**.
48
+
49
+ ### 2.2 Session manager panel
50
+
51
+ Open the **Session manager** panel from the bottom of DSH's sidebar to browse every session, switch workspaces, search by title or ID, apply filters and sorting, and run **Open / Archive / Unarchive / Tags / Notes / Move / Migrate preset / Delete** on any row. The panel header carries the workspace selector, archive filter, favorites / review flags, tag and priority filters, sort order, and matching / total counts plus a reset action.
52
+
53
+ ### 2.3 Bulk management
54
+
55
+ The **Batch process** button in the session manager panel header is the entry point: click it once to enter batch process (row checkboxes appear, the **Select all in filter / Clear selection** pair and the bulk action bar show up); click it again to exit batch process.
56
+
57
+ ## 3 Install
58
+
59
+ ### 3.1 From the official plugin management
60
+
61
+ Go to **plugin management** inside DSH, search for `dsh-session-manager`, and install it.
62
+
63
+ ### 3.2 From dsh-market
64
+
65
+ ```powershell
66
+ dsh plugin --profile web add npm:dsh-session-manager
67
+ ```
68
+
69
+ ### 3.3 From GitHub
70
+
71
+ ```powershell
72
+ dsh plugin --profile web add github:hkkz9522/dsh-session-manager
73
+ ```
74
+
75
+ After installing, restart DSH Web. If the browser still holds an older client bundle, force-refresh with `Ctrl+Shift+R`.
76
+
77
+ ### 3.4 Local development / runtime injection
78
+
79
+ ```text
80
+ dev_inject_plugin {"dir": "<absolute path to this repository>"}
81
+ ```
82
+
83
+ ## 4 Safety and behavior
84
+
85
+ - **Deletion is permanent**, so the UI always asks for confirmation. The API checks the session ID, directory boundary and artifact header before deletion; traversal, symlinks and junctions are refused.
86
+ - Move and preset migration keep the live session / agent alive; only deletion cancels and disposes the session. Move updates the stored `cwd` and the existing live writer's header.
87
+ - The management list hides subagent sessions and the move API rejects them. Blank sessions without a persisted artifact cannot be moved.
88
+ - Cold rewrites preserve the artifact's stored format (V1 / V2 / V3 / V4 are all readable; the plugin never forces an upgrade). Moves and rewrites refuse corrupt / truncated Zstd logs or JSONL logs with incomplete final lines instead of publishing partial history.
89
+ - Preset migration separates backup, publication and rollback. If rollback fails, recovery files are retained and their paths are included in the error; do not remove them.
90
+ - Incomplete startup scans skip workspace reconciliation. Complete scans preserve live sessions and any membership added during the scan.
91
+ - Plugin mutations are serialized per session and request bodies are limited to 64 KiB. This queue supplements, rather than replaces, DSH's own persistence coordination.
92
+
93
+ ## 5 Compatibility
94
+
95
+ | Plugin version | Verified DSH version |
96
+ | --- | --- |
97
+ | 0.5.2 | v0.1.7-rc.1 |
98
+ | 0.5.1 | v0.1.6-alpha.2 |
99
+ | 0.4.11 | v0.1.5-rc.2 |
100
+ | 0.4.10 | v0.1.5-rc.1 |
101
+ | 0.4.9 | v0.1.5-rc.1 |
102
+ | 0.4.7 | v0.1.5-rc.1 |
103
+ | 0.4.6 | 0.1.3-alpha.2 |
104
+ | 0.4.4 | 0.1.3-alpha.2 |
105
+ | 0.4.1 | 0.1.3-alpha.2 |
106
+ | 0.4.0 | v0.1.2-rc.1 |
107
+ | 0.1.2 | v0.1.0-rc.7 |
108
+ | 0.1.1 | v0.1.0-rc.7 |
109
+ | 0.1.0 | v0.1.0-rc.7 |
110
+
111
+ Requires Node.js 22.15+ (22.x) or 24+ for built-in Zstd support.
112
+
113
+ This is a Cordis plugin and declares `cordis: ">=4.0.0-rc <5"` as its peer dependency.
114
+
115
+ ## 6 Development
116
+
117
+ - `lib/index.js` is the host-side ESM plugin; `lib/client.js` is the Web client bundle. No build step is required.
118
+ - Before submitting changes, run:
119
+
120
+ ```powershell
121
+ npm run check
122
+ npm test
123
+ npm run check:package
124
+ git diff --check
125
+ ```
126
+
127
+ Tests use isolated temporary directories and the real plugin entry point, never real sessions. CI runs these checks on Windows / Linux with Node 22.15.0 / 24.
128
+
129
+ Optional integration check: run `node scripts/smoke-test.mjs` against a running test instance of DSH Web. It contacts a real service and is not part of the default unit test suite.
130
+
131
+ Release history is in [CHANGELOG.md](CHANGELOG.md).
132
+
133
+ ## 7 Acknowledgments
134
+
135
+ Thanks to everyone who installs and uses dsh-session-manager, and to the people who file issues and open pull requests to help improve it. The plugin is listed in [dsh-market](https://github.com/dsh-market/dsh-market) and [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin). Suggestions and feedback are welcome.
136
+
137
+ ## 8 License
138
+
139
+ [MIT](LICENSE)