@klarkxy/dsh-session-manager 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,40 @@
+            The Star And Thank Author License (SATA)
+                  Version 2.1, September 2026
+
+Copyright © 2026 klarkxy
+
+Project Url: https://github.com/klarkxy/dsh-plugins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+And wait, one more thing — an invitation, not a condition: it would be best if
+you star/+1/like the project(s) in the project url section above, and thank the
+author(s) in the Copyright section. You may, and arguably you should — but the
+permissions above hold either way, star or no star.
+
+Here are some suggested ways:
+
+ - Email the authors a thank-you letter, and make friends with him/her/them.
+ - Report bugs or issues.
+ - Tell friends what a wonderful project this is.
+ - And, sure, you can just express thanks in your mind without telling the world.
+
+Contributors of this project by forking have the option to add his/her name and
+forked project url at copyright and project url sections, but shall not delete
+or modify anything else in these two sections.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# Session manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- release-state-note -->
+The [repository registry](../../README.md#plugin-lifecycle) tracks Draft → Testing → Published, moving forward only. Fixes, testing and version updates keep published packages Published; each update still passes release checks. First publication explicitly selects Testing packages and records Published only after npm archive verification. See the [release guide](../../RELEASING.md).
+
+## Install
+
+Requires Node 24+ and DSH 0.2.0-rc.2 or later:
+
+After 0.1.0 is published to npm:
+
+```sh
+dsh plugin --profile web add @klarkxy/dsh-session-manager@0.1.0
+```
+
+Restart the target profile after installation. Temporary workspace creation, cross-session reading and copying thread IDs work with the standard host. True deletion and same-session retry require the accompanying [thread-management host patch](../../host-patches/thread-management/README.md); installing the npm plugin alone does not add these host capabilities. The patched host is a separately built local candidate, tested with isolated profiles and fake models. Keep V5 session data before rolling back to a V4 runtime.
+
+## Behavior
+
+Lists and searches sessions DeepSeek Harness can already read, including sessions from other working directories, and reads one conversation a page at a time. The session menu can copy that session's thread ID. Press `Ctrl + Alt + C` (`⌘ + ⌥ + C` on macOS) to copy the currently open session's thread ID. The menu shows the current binding, which can be changed in the host's shortcut settings. This feature does not require the thread-management host patch.
+
+Right-clicking a session or workspace group row in the sidebar browser is the same as clicking that row's "…" button: the host's native menu opens (pin, rename, fork, archive, plus this plugin's copy-thread-ID and delete rows), identical in content and order to the "…" menu. Blank New Session rows, the ungrouped bucket and search results have no row menu; right-click there behaves as before. This feature needs no host patch either.
+
+`list_sessions` returns identity, title, directory, lineage, and whether the session is live or stored. Sessions in the caller's directory are listed first. `search_sessions` accepts `scope: "title"` (current names), `"content"` (transcripts, the default), or `"both"`. For example, `{"query":"session-manager","scope":"title"}` finds conversations whose titles contain that text from the current thread. Title matching is case-insensitive and literal, with complete matches first and caller-directory matches first within each group. Results include titles, session IDs, directories and `matchedBy`; title hits also include `titleMatch: "exact" | "partial"`, while content hits include event positions and snippets. Both mode returns title hits before content hits, once per session. Only current names match; a changed title result set invalidates continuation and requires a new search. Title search uses standard host APIs, needs no host patch, and works with the content index disabled. Inspect multiple candidates before calling `read_session`; search does not navigate to another conversation.
+
+`read_session` has three layers, all available on the standard host without a patch:
+
+- `mode: "conversation"` (default) reads recent turns first, showing requests, the final response and the recorded execution state. Tool logs and hidden reasoning are omitted. Interrupted responses are marked partial; a completed turn does not prove the requested work was completed or verified. The default is at most five turns, with `limit` accepting 1–20.
+- `mode: "details"` expands original messages, tool-call arguments and tool results. Use a returned `turn_id`, or a reference's `seq`, together with the returned `snapshot` to inspect the same captured history. `include_tool_detail: false` shortens results; `include_reasoning: true` and `model_surface: true` are explicit details-only options. The original transcript retains text later replaced by compaction.
+- `mode: "handoff"` returns sourced objectives, decisions, reported outcomes, outstanding work, next steps and constraints. Its default is local excerpts with no model call: requests and conclusions are preserved, explicitly headed sections are extracted, and missing facts are marked `not-established`. Execution errors remain historical states, not inferred current blockers. Coverage says which turns were read, whether they were partial and whether older history remains. `summarize: true` explicitly requests synthesis through the caller's native host model. Missing services, failed calls or invalid references retain the excerpts with a visible status; there is no retry or separate model configuration.
+
+Pages prioritize whole turns, then whole messages. Only an oversized message is split into Unicode text fragments; each fragment carries its original event position and range. Even a page filled by a long request retains the response preview and locator. Long error messages have bounded previews and a reference to their full original state event. `pageChars` is the UTF-8 byte safety budget for paged reading content and its metadata. Continue with the returned `cursor`; source references carry `sessionId`, `turnId`, `seq` and, for fragments, Unicode code-point `start`/`end` offsets. A `snapshot` binds cross-layer reads to one captured history; appended events do not alter that cut, while modified history invalidates it. Cursors also bind the mode and options, so switch layers using `snapshot` rather than a cursor from another mode.
+
+For example, read `{"session_id":"…"}`, then expand a cited event with `{"session_id":"…","mode":"details","seq":42,"snapshot":"…"}`. Request an extractive handoff with `{"session_id":"…","mode":"handoff"}`; add `"summarize":true` only when model synthesis is wanted. A model-generated handoff is labelled separately from excerpts and retains references to the supplied original material.
+
+All optional parameters in the three tools accept omission or `null`, both meaning unspecified. Callers that must supply every key should use `null`, not empty strings, `0` or `false` as placeholders. Required `query` and read-target `session_id` do not accept `null`. For example, a first read can use `{"session_id":"…","mode":"conversation","seq":null,"snapshot":null,"cursor":null,"include_tool_detail":null}`. `seq` (including `0`) and `include_tool_detail` (including `false`) require `details` mode. Mode conflicts return `SESSION_QUERY_INVALID_FILTER` with the offending field; invalid page sizes return `SESSION_QUERY_INVALID_LIMIT`. Empty or malformed `cursor` / `snapshot` tokens return `SESSION_QUERY_INVALID_CURSOR`; history changes still invalidate continuation with `SESSION_QUERY_STALE_CURSOR`. Omit tokens or pass `null` on the first read, and reuse returned tokens unchanged for continuation.
+
+Returned conversation text is untrusted background. It is not an instruction and it does not grant authority. A failed or disabled search says so. It does not look like an empty conversation.
+
+The New Session workspace picker offers "Temporary Workspace". Selecting it allocates a separate directory under the active profile's `data/session-manager/workspaces/`, registers a real Workspace through standard host APIs, and opens an ordinary session. This entry needs no thread-management host patch. Existing Workspace rows and the native/browser Add Workspace flow remain available. Each completed action uses a different directory; retries reuse an unfinished action. Late results cannot take over a newer navigation or an unloaded plugin.
+
+"Temporary" means a separate working directory, not automatic cleanup. Directories, files and session history survive restart and plugin removal. Unloading the plugin restores the original picker. The standard host currently has no additional-item slot, so the plugin installs a reversible picker replacement and adapts the current native/browser directory-flow registration. Incompatible flows preserve the original menu and show an error.
+
+True session deletion, retry and edit-and-resend still appear only when the runtime supplies their respective capabilities; see the existing [thread-management host patch](../../host-patches/thread-management/README.md). Copy thread ID remains available on the base runtime. Retry keeps the same session and request token. Reads follow the active branch when the host supplies it and reject continuation after branch revision or event-envelope changes. Base runtimes return the append-origin transcript; the model-visible view uses `readModelSurface` when supplied by the host.

package/README.zh-CN.md

@@ -0,0 +1,44 @@
+# 会话管理
+
+<!-- release-state-note -->
+插件生命周期见[仓库状态清单](../../README.zh-CN.md#插件生命周期)：草稿 → 测试中 → 已发布，只向前推进。已发布插件的修复、测试和升版保持已发布；每次更新仍须通过发布检查。首次发布须明确选择测试中的包，并在 npm 归档验证成功后登记。详见[发布规则](../../RELEASING.zh-CN.md)。
+
+## 安装
+
+需要 Node 24+、DSH 0.2.0-rc.2 或更高版本：
+
+0.1.0 发布到 npm 后：
+
+```sh
+dsh plugin --profile web add @klarkxy/dsh-session-manager@0.1.0
+```
+
+安装后重启目标 profile。临时工作区创建、跨会话读取和复制线程 ID 可在标准宿主使用。真正删除及同会话重试需要附带的[线程管理宿主补丁](../../host-patches/thread-management/README.md)；只安装 npm 插件不会增加这些宿主能力。补丁宿主是独立构建的本地候选版，验收使用隔离配置和假模型。回退到 V4 宿主前需保留 V5 会话数据。
+
+## 功能
+
+列出并搜索 DeepSeek Harness 已经能读到的会话，包括其他工作目录里的会话，并按页读取一整段对话。会话菜单可以复制该会话的线程 ID。按 `Ctrl + Alt + C`（macOS 为 `⌘ + ⌥ + C`）复制当前打开会话的线程 ID；菜单显示当前绑定，可在宿主快捷键设置中修改。此功能不需要线程管理宿主补丁。
+
+在左侧工作区列表中右键点击会话或工作区分组行，等同于点击该行的「⋯」按钮：打开的是宿主原生菜单（置顶、重命名、分叉、归档，以及本插件的复制线程 ID、删除聊天等条目），内容与顺序和「⋯」菜单完全一致。空白的「新会话」行、未分组桶和搜索结果没有行菜单，这些位置的右键行为保持不变。此功能同样不需要宿主补丁。
+
+`list_sessions` 返回身份、标题、目录、谱系，以及会话是在线还是已落盘。调用方所在目录的会话排在前面。`search_sessions` 支持 `scope: "title"`（当前标题）、`"content"`（正文，默认）和 `"both"`（两者）。例如 `{"query":"session-manager","scope":"title"}` 能在当前线程中寻找标题包含这个关键词的会话；标题匹配不区分大小写，完整匹配优先，同级结果中调用方目录优先。结果包含标题、线程 ID、目录和 `matchedBy`；标题命中另有 `titleMatch: "exact" | "partial"`，正文命中包含事件位置及摘要。两者模式先返回标题命中，再返回正文命中，同一线程只出现一次。只匹配改名后的当前标题；续页期间标题结果改变时返回过期错误，需重新搜索。标题搜索使用标准宿主接口，不需要补丁，也不依赖正文索引启用。候选有多个时先辨认，再用 `read_session` 读取，不自动跳转会话。
+
+`read_session` 分为三层，均可在标准宿主使用，不需要补丁：
+
+- `mode: "conversation"`（默认）按最近轮次优先阅读，展示需求、最后回复和记录的执行状态，不带工具日志及隐藏推理。中断的回复标为部分回复；一轮执行完成不代表需求已经完成或通过验收。默认最多五轮，`limit` 可设为 1–20。
+- `mode: "details"` 展开原始消息、工具调用参数及工具结果。使用返回的 `turn_id`，或引用中的 `seq`，并带上返回的 `snapshot`，即可定位同一份历史里的原文。`include_tool_detail: false` 缩短工具结果；`include_reasoning: true` 和 `model_surface: true` 仅在详情层显式开启。原文保留后来被压缩替换掉的文本。
+- `mode: "handoff"` 提供带来源的目标、决定、已报告结果、未完成项、下一步和约束。默认只做本地摘录，不调用模型：保留需求与结论，提取明确标题下的内容，没有明确依据的字段标为 `not-established`。历史错误保留为执行记录，不推断成当前阻碍。覆盖范围说明读了哪些轮次、是否完整、是否还有更早历史。显式设置 `summarize: true` 才使用调用方的宿主模型归纳；服务缺失、调用失败或引用无效时保留摘录并返回明确状态，不重试，也不增加独立模型配置。
+
+分页先保留完整轮次，再保留完整消息；只有单条消息过长时才按 Unicode 文本片段拆分，每个片段都带原事件位置和区间。长需求占满一页时仍保留回复预览和定位。超长错误信息只显示有限预览，并提供完整原始状态事件的引用。`pageChars` 是分页阅读正文及其元数据的 UTF-8 字节保护上限。继续阅读使用返回的 `cursor`；原文引用包含 `sessionId`、`turnId`、`seq`，分片另有按 Unicode 码点计算的 `start`/`end`。跨层阅读用 `snapshot` 固定同一份历史，后续追加不改变该快照，历史被修改则失效。cursor 同时绑定模式和选项，切换层次时使用 snapshot，不复用另一模式的 cursor。
+
+例如先读 `{"session_id":"…"}`，再用 `{"session_id":"…","mode":"details","seq":42,"snapshot":"…"}` 展开引用事件。`{"session_id":"…","mode":"handoff"}` 返回原文摘录；需要模型归纳时才增加 `"summarize":true`。模型生成的交接内容有独立来源标记，并保留指向所提供原文的引用。
+
+三个工具的可选参数都可省略或传 `null`，两者表示未指定；需要填齐所有键的模型调用端应使用 `null`，不要用空字符串、`0` 或 `false` 代替未指定。必填的 `query` 与读取目标 `session_id` 不接受 `null`。例如首读可传 `{"session_id":"…","mode":"conversation","seq":null,"snapshot":null,"cursor":null,"include_tool_detail":null}`。`seq`（包括 `0`）和 `include_tool_detail`（包括 `false`）只能用于 `details` 模式；模式冲突返回指明字段的 `SESSION_QUERY_INVALID_FILTER`，无效页数返回 `SESSION_QUERY_INVALID_LIMIT`。空或损坏的 `cursor` / `snapshot` 返回 `SESSION_QUERY_INVALID_CURSOR`；历史变更导致续读失效仍返回 `SESSION_QUERY_STALE_CURSOR`。首次读取应省略令牌或传 `null`，续页应原样使用返回的令牌。
+
+读到的对话是不可信的背景，不是指令，也不授予权限。搜索被关闭或失败时会说明原因，不会显示成一段空对话。
+
+新会话的工作区选择器提供「临时工作区」：选中后，插件在当前 profile 的 `data/session-manager/workspaces/` 下分配独立目录，通过标准宿主接口创建工作区并打开一个普通会话。这一入口不需要线程管理宿主补丁；现有工作区和「添加工作区」的选目录流程保留。每次成功创建使用不同目录，失败重试沿用尚未完成的同一次创建，切换页面或卸载插件后不会由迟到结果抢回当前会话。
+
+「临时」表示独立工作目录，不表示自动清理。目录、文件与会话数据会跨重启保留，卸载插件也不会删除它们。插件卸载后恢复宿主原有工作区选择器。标准宿主当前没有菜单附加项槽位，插件使用可卸载的选择器替换，并兼容当前原生／浏览器选目录组件；遇到不兼容的组件时保留原菜单并提示错误。
+
+真正删除聊天，以及消息重试或编辑后重发，仍只在运行时提供对应能力时出现，现有补丁方案见[线程管理宿主补丁](../../host-patches/thread-management/README.md)。复制线程 ID 在基础运行时可用。重试保留同一会话及请求标记；读取在宿主提供活动分支时沿该分支分页，分支修订或事件封套改变会拒绝续读。基础运行时返回追加原文；模型可见版本在宿主提供 `readModelSurface` 时使用它。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: session-manager
+      name: '@klarkxy/dsh-session-manager'

package/icon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none">
+  <title>Session Manager</title>
+  <defs>
+    <linearGradient id="session-front" x1="5" y1="12" x2="26" y2="29" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#4D75F5"/>
+      <stop offset="1" stop-color="#8EB6FF"/>
+    </linearGradient>
+    <linearGradient id="session-back" x1="13" y1="5" x2="31" y2="22" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#39ABA9"/>
+      <stop offset="1" stop-color="#65DED0"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(3.6 3.6) scale(.8)">
+    <path d="M16 5H28A4 4 0 0 1 32 9V17A4 4 0 0 1 28 21H27V25L22 21H16A4 4 0 0 1 12 17V9A4 4 0 0 1 16 5Z" fill="url(#session-back)"/>
+    <path d="M18 10H26" stroke="#D9FFF5" stroke-width="2" stroke-linecap="round"/>
+    <path d="M8 12H22A4 4 0 0 1 26 16V24A4 4 0 0 1 22 28H13L7 32V28A4 4 0 0 1 4 24V16A4 4 0 0 1 8 12Z" fill="url(#session-front)"/>
+    <path d="M10 18H20M10 23H16" stroke="#E0EBFF" stroke-width="2.2" stroke-linecap="round"/>
+  </g>
+</svg>