dsh-session-ops 0.0.0-stage → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cooper Zhuang
+
+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.
+
+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,118 @@
-# Temporary Holding Version
+# dsh-session-ops
 
-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.
+Session operations for DeepSeek Harness (DSH): **really delete** persisted sessions and **move**
+sessions between workspaces while keeping the workspace registry consistent.
+
+One package, one host-plugin row, two halves:
+
+| Half | What it does | Entry points |
+| --- | --- | --- |
+| delete | filter by workspace / archive / subagent, batch select, per-session guards; removes data from disk | HTTP `/session-admin/api/*`, model tool `session_admin`, right-pane "会话管理" tab, conversation-header trash icon, settings page "会话工具" |
+| move | relocate the log, rewrite `header.cwd`, follow workspace membership; optional memory follow (off by default) | HTTP `/session-move/api/*`, model tool `session_move`, right-pane "会话归位" tab, session context menu |
+
+The session-storage primitives live in this package under `lib/store/` (project-directory key
+codec, `session[.vN].jsonl[.zstd]` frame read/write, workspace registry, `$DSH_HOME` and file
+logging, HTTP plumbing) and are shared by both halves.
+
+## Install
+
+```bash
+dsh plugin --profile <profile> add dsh-session-ops
+```
+
+Restart the host afterwards (or let DSH recompose the profile according to its hot-load rules).
+The plugin row is declared in the bundled `cordis.patch.yml`; its entry id is `session-toolbox`.
+
+## ⚠️ Destructive deletion
+
+"Delete" means **really delete**, not archive:
+
+- `<DSH_HOME>/sessions/<project-key>/<session-id>/` (session log)
+- `<DSH_HOME>/storages/session_projcache/sessions/<session-id>.json` (projection cache)
+- `<DSH_HOME>/rewind-snapshots/<session-id>/` (rewind snapshots, if present)
+
+All three are removed from disk, and project directories left empty are cleaned up. **There is no
+trash and no undo.** Back up `$DSH_HOME` yourself; the panel provides a dry run and two
+confirmations, but the operator owns the outcome.
+
+Safe defaults (configurable): `allowWorkspaceSessions=false`, `allowLiveSessions=false`,
+`refuseRunning=true` — workspace sessions, live sessions and mid-turn moves are refused by default.
+
+A move is not a delete: the session directory is relocated from the old project directory to the
+new one, `header.cwd` is rewritten, and workspace membership follows. On kernel 0.2.2+
+`session.lock` moves with it (same inode); if the target already holds a lease the move is refused
+outright rather than leaving a split lease.
+
+## Configuration
+
+The plugin row has one shared `enabled` master switch; every other key is independent:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | master switch; `false` registers no routes, tools or slots |
+| `root` | `''` | session root override; empty derives it from `$DSH_HOME/sessions` |
+| `adminAllowHosts` | `[]` | delete-half LAN trust list (parsed from the `Host` header) |
+| `moveAllowHosts` | `[]` | move-half LAN trust list (exact socket `remoteAddress` match) |
+| `headerDeleteButton` | `true` | conversation-header trash icon (icon + two confirmations) |
+| `allowWorkspaceSessions` | `false` | allow deleting sessions that belong to a workspace |
+| `allowLiveSessions` | `false` | allow deleting sessions still loaded in the host |
+| `maxBatch` | `200` | per-call batch delete limit |
+| `refuseRunning` | `true` | refuse moving a session that is mid-turn |
+| `maxSessions` | `2000` | max sessions listed by the move panel |
+| `memoryFollow` | `off` | project-memory follow: `off` / `copy` / `move` (`move` is irreversible) |
+| `repairForkChildrenOnBoot` | `true` | re-file fork children whose membership was lost, at boot |
+
+The two trust keys **cannot** be merged: the delete half parses the `Host` header and additionally
+rejects `sec-fetch-site: cross-site` and cross-origin `Origin`, while the move half matches the
+socket address exactly. Merging them would loosen one half. Both only affect LAN access; loopback is
+always trusted.
+
+The browser half registers one config card on the Plugins page: slot `plugins.bundle.config`, key =
+the package name `dsh-session-ops`, carrying the seven volatile knobs (4 delete + 3 move). Saving
+writes back to the profile's `cordis.patch.yml`; no restart needed.
+
+## Compatibility
+
+- Node.js `>=24`
+- DSH `^0.2.1-rc.2 || ^0.2.2-alpha.2`
+
+The session context menu needs the kernel's `@deepseek-ai/dsh-client-ui-context-menu` service
+(0.2.2+); without it only those two menu entries are missing — tabs, tools and HTTP endpoints keep
+working. Moving `session.lock` and the boot-time fork-child repair both follow the 0.2.2+
+persistence implementation.
+
+## Troubleshooting artifacts
+
+Two file logs keep their original line formats (historical artifacts, deliberately not unified):
+
+- `$DSH_HOME/logs/dsh-session-admin.log` — `[iso] level message`
+- `$DSH_HOME/logs/dsh-session-move.log` — `iso [level] message`
+
+Key move/repair lines: `membership repair mounted`, `membership: attached fork child …`,
+`membership: attach failed …`, `membership sweep: re-attached N of M fork child(ren) …`.
+
+## Using it as a library
+
+`lib/store/` is independent of the plugin lifecycle and has zero `@deepseek-ai/*` dependencies, so it
+can be imported on its own. Two entries are published:
+
+```js
+// package root: same surface as the former shared session-store entry
+import { projectKey, readSessionHeader, hasZstd } from 'dsh-session-ops'
+
+// or the explicit layered subpath
+import { projectKey, readSessionHeader, hasZstd } from 'dsh-session-ops/store'
+```
+
+## Development
+
+```bash
+npm test          # node --test: all use cases from both halves plus lib/store
+```
+
+`lib/` is hand-written source, not build output; `lib/client.js` is an IIFE for the browser classic
+script loader and can be validated with `node --check`.
+
+## License
+
+MIT © 2026 Cooper Zhuang

package/README.zh.md

@@ -0,0 +1,111 @@
+# dsh-session-ops
+
+DeepSeek Harness（DSH）的**会话运维插件**：真删除会话、把会话搬到另一个工作区，并把工作区成员关系修好。
+
+一个包、一个插件行，包含两个半边：
+
+| 半边 | 能力 | 入口 |
+| --- | --- | --- |
+| 删除 | 按工作区 / 归档 / 子代理筛选、批量选择、逐条守卫；真删磁盘数据 | HTTP `/session-admin/api/*`、模型工具 `session_admin`、右栏「会话管理」页签、会话标题栏垃圾桶、设置页「会话工具」 |
+| 搬迁 | 搬日志、改写 header 的 `cwd`、跟随工作区成员表；可选项目记忆跟随（默认关） | HTTP `/session-move/api/*`、模型工具 `session_move`、右栏「会话归位」页签、会话右键菜单 |
+
+会话存储原语（项目目录键编解码、`session[.vN].jsonl[.zstd]` 帧读写、工作区注册表、
+`$DSH_HOME` 与文件日志、HTTP 底座）收在本包的 `lib/store/`，两个半边共用同一份实现。
+
+## 安装
+
+```bash
+dsh plugin --profile <profile> add dsh-session-ops
+```
+
+装好后重启宿主（或按 DSH 的热加载规则让 profile 重组）。插件行由包内
+`cordis.patch.yml` 声明，entry id 是 `session-toolbox`。
+
+## ⚠️ 破坏性删除
+
+「删除」是**真删除**，不是归档：
+
+- `<DSH_HOME>/sessions/<项目目录键>/<session-id>/`（会话日志）
+- `<DSH_HOME>/storages/session_projcache/sessions/<session-id>.json`（投影缓存）
+- `<DSH_HOME>/rewind-snapshots/<session-id>/`（回退快照，若有）
+
+三处一起从磁盘移除，并顺手清理因此变空的项目目录。**没有回收站，删了无法恢复。**
+删除前请自行备份 `$DSH_HOME`；面板提供预演与二次确认，但最终责任在操作者。
+
+默认安全边界（可在配置里改）：`allowWorkspaceSessions=false`、`allowLiveSessions=false`、
+`refuseRunning=true` —— 工作区会话、正在跑的会话、运行中的搬迁默认都被拒绝。
+
+搬迁不是删除：日志目录从旧 project 目录整体移到新目录，`header.cwd` 改写，工作区
+成员表跟着变；0.2.2+ 内核里 `session.lock` 会一起搬走（inode 不变），目标目录已有
+租约时直接拒绝，不会制造「锁在旧目录、日志在新目录」的半套状态。
+
+## 配置
+
+插件行只有一个 `enabled` 总开关，两半共用；其余键各自独立：
+
+| 键 | 默认 | 作用 |
+| --- | --- | --- |
+| `enabled` | `true` | 总开关；`false` 时不注册任何路由、工具、槽位 |
+| `root` | `''` | 会话根目录；空表示用 `$DSH_HOME/sessions` |
+| `adminAllowHosts` | `[]` | 删除半边的 LAN 信任列表（按 `Host` 头解析 host/hostname 匹配） |
+| `moveAllowHosts` | `[]` | 搬迁半边的 LAN 信任列表（按 socket `remoteAddress` 精确匹配） |
+| `headerDeleteButton` | `true` | 会话标题栏垃圾桶图标（图标 + 两步确认） |
+| `allowWorkspaceSessions` | `false` | 允许删除已归属工作区的会话 |
+| `allowLiveSessions` | `false` | 允许删除宿主里驻留的会话 |
+| `maxBatch` | `200` | 单次批量删除上限 |
+| `refuseRunning` | `true` | 拒绝搬迁正在跑一轮的会话 |
+| `maxSessions` | `2000` | 搬迁面板一次最多列出的会话数 |
+| `memoryFollow` | `off` | 项目记忆跟随：`off` / `copy` / `move`（`move` 不可逆） |
+| `repairForkChildrenOnBoot` | `true` | 启动时补挂漏记账的 fork 子会话 |
+
+两个信任键**不能合并**：删除半边按 `Host` 头并拒绝 `sec-fetch-site: cross-site` 与
+跨源 `Origin`，搬迁半边按 socket 地址精确匹配；合成一个等于放宽其中一边。两者都只
+影响 LAN 访问，loopback 始终被信任。
+
+浏览器侧还有一处指向本行的配置卡片：槽 `plugins.bundle.config`，key 是包名
+`dsh-session-ops`，7 个 volatile 旋钮（删除 4 + 搬迁 3）保存即写回 profile 的
+`cordis.patch.yml`，无需重启。
+
+## 兼容区间
+
+- Node.js `>=24`
+- DSH `^0.2.1-rc.2 || ^0.2.2-alpha.2`
+
+会话右键菜单需要内核提供 `@deepseek-ai/dsh-client-ui-context-menu`（0.2.2+）；没有这个
+服务时只少两个菜单项，页签、工具与 HTTP 入口照旧。搬迁时携带 `session.lock`、
+启动期 fork 子会话补记账同样以 0.2.2+ 的持久化实现为准。
+
+## 排障产物
+
+两份文件日志保留各自原有的行格式（历史产物，刻意不统一）：
+
+- `$DSH_HOME/logs/dsh-session-admin.log` —— `[时间] 级别 正文`
+- `$DSH_HOME/logs/dsh-session-move.log` —— `时间 [级别] 正文`
+
+搬迁与自愈的关键行：`membership repair mounted`、`membership: attached fork child …`、
+`membership: attach failed …`、`membership sweep: re-attached N of M fork child(ren) …`。
+
+## 作为库使用
+
+`lib/store/` 与插件生命周期无关、零 `@deepseek-ai/*` 依赖，可以单独引用。包里提供两种入口：
+
+```js
+// 根入口（与合并前的会话存储共享库公开面一致）
+import { projectKey, readSessionHeader, hasZstd } from 'dsh-session-ops'
+
+// 或显式分层，避免和插件面混在一起
+import { projectKey, readSessionHeader, hasZstd } from 'dsh-session-ops/store'
+```
+
+## 开发
+
+```bash
+npm test          # node --test：两个半边全部用例 + lib/store 用例
+```
+
+`lib/` 是手写源码，不走构建；`lib/client.js` 是给浏览器经典脚本加载器用的 IIFE，
+直接用 `node --check` 即可校验。
+
+## License
+
+MIT © 2026 Cooper Zhuang

package/cordis.patch.yml

@@ -0,0 +1,38 @@
+# dsh-session-ops bundle patch: mount the single host-plane plugin row.
+#
+# 合并包：一个插件行同时提供原先两个插件的能力。
+#   - 删除（原 dsh-session-admin）：HTTP /session-admin/api，模型工具 session_admin，
+#     右栏「会话管理」页签，会话标题栏垃圾桶图标，设置页「会话清理」卡片。
+#   - 搬迁（原 dsh-session-move）：HTTP /session-move/api，模型工具 session_move，
+#     右栏「会话归位」页签（含左栏底部入口）。
+# 两个半边共用本行的这一份配置；插件页上本行的「配置」卡片就是合并后的那张（7 个旋钮）。
+#
+# 从旧的两个插件行迁过来时，配置键要改写（旧 allowHosts 语义不同，已拆成两个键）：
+#   dsh-session-admin 行：enabled→enabled, allowHosts→adminAllowHosts,
+#     headerDeleteButton/allowWorkspaceSessions/allowLiveSessions/maxBatch 同名保留。
+#   dsh-session-move 行：enabled→enabled, allowHosts→moveAllowHosts,
+#     root/refuseRunning/maxSessions/memoryFollow 同名保留。
+# 注意：enabled 从「每半一个」变成一个（总开关）。旧 profile 里残留的 allowHosts
+# 不会被任何栅栏读取（schemastery 容忍未知键，不会报错），也就是会**静默失效**——
+# 需要 LAN 访问的话，必须把它改写成 adminAllowHosts / moveAllowHosts。
+#
+# 安全默认（一字未变）：
+#   admin/headerDeleteButton=true（垃圾桶是图标 + 两步确认，不是带标签的按钮）
+#   admin/allowWorkspaceSessions=false, admin/allowLiveSessions=false, admin/maxBatch=200
+#   move/refuseRunning=true, move/maxSessions=2000, move/memoryFollow=off
+- insert:
+    - id: session-toolbox
+      name: dsh-session-ops
+      config:
+        enabled: true
+        root: ''
+        adminAllowHosts: []
+        moveAllowHosts: []
+        headerDeleteButton: true
+        allowWorkspaceSessions: false
+        allowLiveSessions: false
+        maxBatch: 200
+        refuseRunning: true
+        maxSessions: 2000
+        # off（默认）| copy | move —— 见本包 README「配置」一节的 memoryFollow。
+        memoryFollow: off

package/docs/DETAIL.md

@@ -0,0 +1,24 @@
+# Session operations
+
+Turns the session-to-workspace binding into an explicit tool: really delete sessions and move them
+between workspaces while keeping the registry consistent.
+
+## Two right-pane tabs
+  - Delete: filter by workspace, archive or subagent; batch select; running sessions refused by default.
+  - Move: relocate the log, rewrite header cwd, follow workspace membership; optional memory follow (off).
+
+## Other entry points
+  - Session context menu: move / delete.
+  - Model tools session_admin, session_move; host HTTP /session-admin/api, /session-move/api.
+
+## Shared storage primitives (`lib/store`)
+  - `paths.js`: project-directory key codec (`projectKey` / `encodeSegment`), session and generation file naming.
+  - `frames.js`: `session[.vN].jsonl[.zstd]` frame scanning, header read (two strictness levels), cwd rewrite.
+  - `registry.js`: workspace membership and archive sets, resident sessions, mid-turn detection, write-handle redirection.
+  - `host.js`: `$DSH_HOME`, best-effort file logging, volatile config unwrapping.
+  - `http.js`: shared JSON response / request-body plumbing and the prefixed route skeleton.
+
+## Notes
+  - A move carries session.lock (0.2.2+ write lease) and empties the source directory; it refuses when the target already holds a lease.
+  - On boot a narrow fork-child membership repair runs (repairForkChildrenOnBoot, default on).
+  - Deletion is permanent: no trash, no undo. Back up `$DSH_HOME` before using it.

package/docs/DETAIL.zh.md

@@ -0,0 +1,23 @@
+# 会话运维
+
+把 DSH 的「会话 → 工作区」绑定关系做成可操作的工具：真实删会话、把会话搬到另一个工作区，并把成员关系修好。
+
+## 两个页签
+  - 删除：按工作区、归档、子代理筛选，批量选择；运行中会话默认拒绝。
+  - 搬迁：列出会话与归属，选择目标工作区后搬日志、改 header cwd、跟随注册表成员；支持记忆条目跟随（默认关）。
+
+## 其他入口
+  - 会话右键菜单：移动会话到工作区…、删除会话…
+  - 模型工具 session_admin、session_move；宿主 HTTP /session-admin/api、/session-move/api。
+
+## 共享存储原语（`lib/store`）
+  - `paths.js`：项目目录 key 编解码（projectKey / encodeSegment）、会话目录与 generation 文件名规则。
+  - `frames.js`：`session[.vN].jsonl[.zstd]` 帧扫描、header 读取（两种严格度）、cwd 改写。
+  - `registry.js`：工作区成员表 / 归档集合、驻留会话、「正在跑一轮」判定、写入句柄重定向。
+  - `host.js`：`$DSH_HOME`、尽力而为的文件日志、volatile 配置解包。
+  - `http.js`：JSON 响应 / 请求体读取底座与前缀路由骨架。
+
+## 注意
+  - 搬迁会把 session.lock 一起搬走（0.2.2+ 写租约），源目录清空；目标已有租约时拒绝。
+  - 启动时会做一次 fork 子会话的定向补记账（repairForkChildrenOnBoot，默认开）。
+  - 删除是永久性的：没有回收站、无法恢复，操作前请备份 `$DSH_HOME`。

package/icon.svg

@@ -0,0 +1 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="6" y="12" width="24" height="16" rx="3" fill="#F59E0B"/><path d="M6 12l3-5h6l2 5M21 12l2 5h7" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>