dsh-session-ops 0.0.0-stage → 0.1.4

package/lib/store/paths.js

@@ -0,0 +1,163 @@
+/**
+ * 会话存储的**路径命名**知识：项目目录键（`--C-proj--`）、会话目录、generation 文件名。
+ *
+ * 这些命名事实原本分散在两个插件里，而且是同一份知识的**两个方向**：
+ *   - `dsh-session-move` 需要**正向**编码（`projectKey` / `encodeSegment`）——搬迁时
+ *     要把会话日志放到目标 cwd 对应的 project 目录；
+ *   - `dsh-session-admin` 需要**反向**还原（`decodeProjectKey`）——删除面板要给出
+ *     「这条会话大概是哪个目录的」，而头部读不出来时只有目录键可猜。
+ * 两份实现各自维护同一套规则，改动任何一边都要记得另一边——这就是本模块存在的理由。
+ *
+ * 规则（与 `dsh-session-persistence-jsonl` 的 `format.js` 逐字一致）：
+ *   - 路径里每个非 `[A-Za-z0-9._-]` 的码位写成 `~XXXX`（大写十六进制、四位）；
+ *   - `/` `\` `:` 三种分隔符**折叠成 `-`**（盘符的冒号也因此变成 `-`）；
+ *   - 目录键形如 `--<readable>--`，`readable` 截断到 251 字符；
+ *   - 会话目录 = `<root>/<projectKey(cwd)>/<encodeSegment(id)>`。
+ *
+ * @module dsh-session-ops/store/paths
+ */
+
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** generation 规范名：`session.jsonl[.zstd]` 或 `session.vN.jsonl[.zstd]`。 */
+const GENERATION_NAME = /^session(?:\.v(\d+))?\.jsonl(\.zstd)?$/
+
+/**
+ * 把任意字符串编码成一个安全路径段（与会话 id 共用同一套转义）。
+ * @param raw - 原始字符串。
+ * @returns 单个文件系统安全路径段。
+ */
+export function encodeSegment(raw) {
+  if (raw.length === 0) throw new Error('cannot encode an empty path segment')
+  if (raw === '.') return '~002E'
+  if (raw === '..') return '~002E~002E'
+  let out = ''
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i)
+    const ch = String.fromCharCode(code)
+    if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) out += ch
+    else out += '~' + code.toString(16).toUpperCase().padStart(4, '0')
+  }
+  return out
+}
+
+/**
+ * 项目目录键：分隔符折叠成 `-`，不安全码位 `~XXXX`，截断到 251 字符。
+ * @param cwd - 会话的项目目录。
+ * @returns 单个文件系统安全的项目目录名。
+ */
+export function projectKey(cwd) {
+  if (cwd.length === 0) throw new Error('cannot encode an empty project path')
+  let readable = ''
+  let separatorRun = false
+  for (let i = 0; i < cwd.length; i++) {
+    const code = cwd.charCodeAt(i)
+    const ch = String.fromCharCode(code)
+    if (ch === '/' || ch === '\\' || ch === ':') {
+      if (!separatorRun) readable += '-'
+      separatorRun = true
+    } else if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) {
+      readable += ch
+      separatorRun = false
+    } else {
+      readable += '~' + code.toString(16).toUpperCase().padStart(4, '0')
+      separatorRun = false
+    }
+  }
+  return `--${(readable.replace(/^-+/, '') || 'root').slice(0, 251)}--`
+}
+
+/**
+ * 把 `sessions/` 下的项目目录键还原成路径。
+ *
+ * 只做「够用」的反解：分隔符在磁盘上已经全部退化成 `-`，无法区分 `/` 与 `\`
+ * （这里一律还原成 `\`），盘符的冒号也没有单独转义（`C:\a` → `--C-a--`，这里
+ * 按 `^[A-Za-z]\\` 补回来）。**真正的 cwd 以会话头部里的记录为准**，这个只作为兜底。
+ * @param key - 项目目录名。
+ * @returns 反解出的路径。
+ */
+export function decodeProjectKey(key) {
+  let s = key
+  if (s.startsWith('--')) s = s.slice(2)
+  if (s.endsWith('--')) s = s.slice(0, -2)
+  s = s.replace(/~([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+  s = s.replace(/-/g, '\\')
+  // 盘符的冒号在目录键里没有单独转义（`C:\a` → `--C-a--`），补回来。
+  return /^[A-Za-z]\\/.test(s) ? `${s[0]}:${s.slice(1)}` : s
+}
+
+/**
+ * **宽松**的会话日志文件名判定：`.jsonl.zstd` 或 `.jsonl` 结尾就算。
+ *
+ * 与 {@link parseGenerationName}（**规范** generation 名）是两件事，别互相替换：
+ * 删除路径要能看见并清掉任何形状的日志文件（哪怕是手工改名或半截写入的），
+ * 而搬迁路径必须只认规范名，否则会把临时文件当成真日志搬走。
+ * @param name - 目录项名。
+ * @returns 是否像一份会话日志。
+ */
+export function isSessionLogFile(name) {
+  return name.endsWith('.jsonl.zstd') || name.endsWith('.jsonl')
+}
+
+/**
+ * 目录里是不是规范 generation 名。
+ * @param name - 目录项名。
+ * @returns 版本号（v0 为 0）与是否压缩；不是规范名时 `undefined`。
+ */
+export function parseGenerationName(name) {
+  const match = GENERATION_NAME.exec(name)
+  if (match === null) return undefined
+  return { version: match[1] === undefined ? 0 : Number(match[1]), compressed: match[2] === '.zstd' }
+}
+
+/**
+ * 选出会话目录里版本最高的规范 generation 文件。
+ *
+ * 临时名与备份名（`*.session-move-tmp`、`*.session-move-old`）不匹配规范名，
+ * 一律进 `others`——搬迁必须保证「任何时刻都不存在两份规范名日志」。
+ * @param dir - 会话目录。
+ * @returns `{selected, all, others}`；列不了目录或没有规范名时 `{error, others?}`
+ *   （错误文案被两个插件的用户可见报告引用，改动前先看测试）。
+ */
+export function findGeneration(dir) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch (error) {
+    return { error: `cannot list session directory ${dir}: ${String(error?.message ?? error)}` }
+  }
+  const generations = []
+  const others = []
+  for (const entry of entries) {
+    const parsed = parseGenerationName(entry.name)
+    if (parsed === undefined) {
+      others.push(entry.name)
+      continue
+    }
+    generations.push({ name: entry.name, version: parsed.version, compressed: parsed.compressed })
+  }
+  if (generations.length === 0) return { error: `no canonical session log in ${dir}`, others }
+  generations.sort((left, right) => right.version - left.version)
+  return { selected: generations[0], all: generations, others }
+}
+
+/** 物理编码后缀。 */
+export function compressionSuffix(compression) {
+  return compression === 'zstd' ? '.zstd' : ''
+}
+
+/** 一个 generation 的规范文件名（v0 不带 `vN` 段）。 */
+export function generationLogFilename(version, compression) {
+  return `${version === 0 ? 'session' : `session.v${version}`}.jsonl${compressionSuffix(compression)}`
+}
+
+/** 会话目录：`<root>/<projectKey>/<encodeSegment(id)>`。 */
+export function sessionDir(root, cwd, id) {
+  return join(join(root, cwd === undefined ? '_no-cwd' : projectKey(cwd)), encodeSegment(id))
+}
+
+/** 一个 generation 的绝对日志路径。 */
+export function logPath(root, cwd, id, version, compression) {
+  return join(sessionDir(root, cwd, id), generationLogFilename(version, compression))
+}

package/lib/store/registry.js

@@ -0,0 +1,223 @@
+/**
+ * 会话**归属**知识：工作区注册表（`ctx.workspaceRegistry`）、驻留会话、以及「正在跑一轮」。
+ *
+ * 这份知识在两个插件里各有一半，写在一处才不会走形：
+ *   - `dsh-session-admin` 要判断「这条会话属于哪个工作区 / 归档没有」才能决定能不能删，
+ *     并在删文件**之前**把它从登记表里摘掉；
+ *   - `dsh-session-move` 要判断「属于谁 / 目标工作区是哪一个 / 正在跑没有」才能搬，
+ *     并在搬完之后 attach 目标、detach 原属、把内存里缓存的 cwd 一起改掉。
+ *
+ * ## 三个容易踩的坑（都是实测结论，不是推测）
+ *
+ * 1. **`workspace.sessionIds` 是「按会话头索引过滤过的视图」**，不是完整记账：
+ *    DSH 每次读取都用 `realpath(header.cwd) === workspace.path` 过滤一遍。完整记账在
+ *    `workspace.record.sessionIds`（见 {@link accountedSessionIds}）。
+ *    会话目录一删，`sessionIds` 就再也查不到这条会话——所以「摘登记表」必须早于「删文件」。
+ * 2. **「挂着」≠「正在跑」**：会话在创建 agent 时被 enter，只在 agent dispose 时才 detach，
+ *    长期运行的 `dsh web` 里只要碰过就基本一直挂着。删/搬的守卫只认「正在跑一轮」。
+ * 3. **`workspace.json` 里的工作区对象自身不带 id**，id 只存在于外层键上；从磁盘读表时
+ *    必须重新组装视图，否则所有守卫会因为 `owner.workspaceId === undefined` 静默失效。
+ *
+ * 出错时的策略刻意**不统一**，两边各自保留（见各函数的文档）：
+ * 拿不到 `agents` 服务时 admin 保守地把全部驻留会话当成「在跑」（宁可拒绝），
+ * move 则把状态当成未知（`undefined`，界面照常显示）。
+ *
+ * @module dsh-session-ops/store/registry
+ */
+
+/** agent 表示「这一轮还在跑」的状态值。 */
+export const SESSION_RUNNING_STATUS = 'running'
+
+/**
+ * Host 进程里仍挂着的会话 id 集合（`ctx.sessions.list()`）。
+ *
+ * 服务缺失或抛错时退化成空集合——**这个集合只用于界面提示，不要拿它当删除守卫**
+ * （理由见模块注释第 2 条）。
+ * @param sessions - `ctx.get('sessions')` 拿到的会话服务（可为 undefined）。
+ * @returns `Set<string>`。
+ */
+export function residentSessionIds(sessions) {
+  const ids = new Set()
+  try {
+    const list = typeof sessions?.list === 'function' ? sessions.list() : []
+    for (const session of list) ids.add(String(session.id))
+  } catch {
+    /* 没有会话存储时视为无驻留 */
+  }
+  return ids
+}
+
+/**
+ * 一条会话的 agent 状态（`ctx.get('agents').get(id)?.status`）。
+ * @param agents - `ctx.get('agents')` 拿到的 agent 服务（可为 undefined）。
+ * @param sessionId - 会话 id。
+ * @returns 状态字符串；没有 agent、拿不到服务或抛错时 `undefined`（**未知**）。
+ */
+export function agentSessionStatus(agents, sessionId) {
+  try {
+    const agent = typeof agents?.get === 'function' ? agents.get(sessionId) : undefined
+    return agent !== undefined && typeof agent.status === 'string' ? agent.status : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 真正「正在跑一轮」的会话：驻留集合里 agent 状态为 {@link SESSION_RUNNING_STATUS} 的那部分。
+ *
+ * 拿不到 agents 服务时**保守退化**为「全部驻留会话都算在跑」——宁可拒绝，不可误删/误搬。
+ * 单条查询抛错也算在跑（同一条原则）。
+ * @param residents - {@link residentSessionIds} 的结果。
+ * @param agents - `ctx.get('agents')`。
+ * @returns `Set<string>`（可能就是 `residents` 本身）。
+ */
+export function runningSessionIds(residents, agents) {
+  if (agents === undefined || typeof agents.get !== 'function') return residents
+  const running = new Set()
+  for (const id of residents) {
+    try {
+      if (agents.get(id)?.status === SESSION_RUNNING_STATUS) running.add(id)
+    } catch {
+      running.add(id)
+    }
+  }
+  return running
+}
+
+/**
+ * 工作区的**完整记账**成员表（`workspace.record.sessionIds`）。
+ * @param workspace - 工作区实体。
+ * @returns id 数组；实体没有 record 视图时 `undefined`。
+ */
+export function accountedSessionIds(workspace) {
+  const record = workspace?.record
+  return record !== undefined && Array.isArray(record.sessionIds) ? record.sessionIds : undefined
+}
+
+/**
+ * 归档集合（`registry.archivedSessionIds`）。
+ * @param registry - `ctx.workspaceRegistry`。
+ * @returns `Set<string>`（id 归一成字符串）。
+ */
+export function archivedSessionIds(registry) {
+  return new Set(Array.isArray(registry.archivedSessionIds) ? registry.archivedSessionIds.map(String) : [])
+}
+
+/**
+ * 按**完整记账**找出会话所属的工作区。
+ * @param workspaces - 工作区实体数组（通常是 `registry.list()`）。
+ * @param sessionId - 会话 id。
+ * @returns 工作区实体，或 `undefined`。
+ */
+export function workspaceOwningSession(workspaces, sessionId) {
+  for (const workspace of workspaces) {
+    const ids = accountedSessionIds(workspace)
+    if (ids !== undefined && ids.includes(sessionId)) return workspace
+  }
+  return undefined
+}
+
+/**
+ * 按 id → path → title 的顺序找一个工作区（后两者不区分大小写）。
+ * @param workspaces - 工作区实体数组（通常是 `registry.list()`）。
+ * @param key - id、绝对路径或标题；空值一律不匹配。
+ * @returns 工作区实体，或 `undefined`。
+ */
+export function findWorkspace(workspaces, key) {
+  if (typeof key !== 'string' || key.length === 0) return undefined
+  for (const workspace of workspaces) if (String(workspace.id) === key) return workspace
+  const lowered = key.toLowerCase()
+  for (const workspace of workspaces) if (String(workspace.path).toLowerCase() === lowered) return workspace
+  for (const workspace of workspaces) if (String(workspace.title).toLowerCase() === lowered) return workspace
+  return undefined
+}
+
+/**
+ * 把一个即将被删除的会话从它登记过的每个持久结构里摘掉。
+ *
+ * 走 `workspaceRegistry`（宿主的权威登记表）而不是直接改 `storages/workspace.json`：
+ * 宿主自己也把这份表放在内存里，手改文件要么被下一次写入覆盖，要么让内存与磁盘脱节。
+ *
+ * 覆盖三处：工作区成员表、归档集合、置顶集合。后两个是幂等的（不在集合里就不写盘），
+ * 所以无条件调用它们不会产生多余的写入。
+ *
+ * **必须在删文件之前调用**：`Workspace.sessionIds` 是按会话头索引过滤过的视图，
+ * 目录一删，成员关系就再也查不到了。
+ * @param registry - `ctx.workspaceRegistry`。
+ * @param sessionId - 即将删除的会话 id。
+ * @returns 全部持久写入完成之后 resolve；值是真正被 detach 的工作区 id 列表。
+ */
+export async function releaseSessionEverywhere(registry, sessionId) {
+  const detached = []
+  for (const workspace of registry.list()) {
+    if (!workspace.sessionIds.includes(sessionId)) continue
+    await workspace.detachSession(sessionId)
+    detached.push(String(workspace.id))
+  }
+  await registry.unarchiveSession(sessionId)
+  await registry.unpinSession(sessionId)
+  return detached
+}
+
+/**
+ * 持久化后端的**写入句柄表**（`persistence.tracker.writers`）。
+ *
+ * 有句柄 = 这条会话随时可能落盘。搬迁必须抢在它下一次 append 之前把 header 改掉。
+ * @param persistence - `ctx.sessionPersistence`（可为 undefined）。
+ * @returns `Map<id, handle>`，或 `undefined`（后端不暴露 tracker 时）。
+ */
+export function sessionWriteHandles(persistence) {
+  const tracker = persistence?.tracker
+  return tracker !== undefined && tracker.writers instanceof Map ? tracker.writers : undefined
+}
+
+/**
+ * 把「这条会话以后往哪写」在**内存里**也改成新 cwd。
+ *
+ * 搬迁只搬了磁盘上的目录，内存里还有三处记着旧 cwd，漏掉任何一处都会让下一次 append
+ * 写到不存在的位置（ENOENT）：
+ *   1. 持久化写入句柄的 `header`——它每次 append 都从自己的 header 重新推 logPath
+ *      （`appendLines → logPath(meta.cwd)`），所以改 header 就够了；改之前先 `flush()`，
+ *      免得把还没落盘的缓冲写到旧路径；
+ *   2. 驻留会话对象自身的 `header`（工具/界面从它解析 cwd）；
+ *   3. 注册表里的头部缓存（`registry.headers`，`Map<id, header>`）。
+ *
+ * 每一步都独立尽力而为：句柄 flush 失败只记录，不阻断其余改写。
+ * @param options - `{writers, sessions, registry, sessionId, cwd}`；`writers` 来自
+ *   {@link sessionWriteHandles}，`sessions` 是 `ctx.get('sessions')`。
+ * @returns `{writeHandleRedirected, liveHeaderUpdated, registryHeaderCacheUpdated, flushError?, liveSession}`
+ *   ——`flushError` 只在 flush 抛错时出现；`liveSession` 是驻留会话对象（没有则 undefined）。
+ */
+export async function redirectSessionWriters(options) {
+  const { writers, sessions, registry, sessionId, cwd } = options
+  const outcome = {
+    writeHandleRedirected: false,
+    liveHeaderUpdated: false,
+    registryHeaderCacheUpdated: false,
+    liveSession: undefined,
+  }
+  const handle = writers === undefined ? undefined : writers.get(sessionId)
+  if (handle !== undefined && handle !== null && typeof handle.header === 'object') {
+    try {
+      await handle.flush()
+    } catch (error) {
+      outcome.flushError = String(error?.message ?? error)
+    }
+    handle.header = { ...handle.header, cwd }
+    outcome.writeHandleRedirected = true
+  }
+  const live = typeof sessions?.get === 'function' ? sessions.get(sessionId) : undefined
+  outcome.liveSession = live
+  if (live !== undefined) {
+    live.header = { ...live.header, cwd }
+    outcome.liveHeaderUpdated = true
+  }
+  if (registry.headers instanceof Map) {
+    const cached = registry.headers.get(sessionId)
+    if (cached !== undefined) {
+      registry.headers.set(sessionId, { ...cached, cwd })
+      outcome.registryHeaderCacheUpdated = true
+    }
+  }
+  return outcome
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Session operations",
+    "description": "Really delete persisted sessions and move them between workspaces: two right-pane tabs, batch filters, running guards, context-menu entries and shared session-store primitives.",
+    "detail": "docs/DETAIL.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "会话运维",
+    "description": "真实删除与跨工作区搬迁会话：右栏两个页签、批量筛选、运行中守卫、会话右键菜单入口，以及共用的会话存储原语。",
+    "detail": "docs/DETAIL.zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "dsh-session-ops",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Session operations for DeepSeek Harness: really delete persisted sessions (workspace/archive/subagent filters, running-session guards) and move sessions between workspaces (log relocation, header.cwd rewrite, workspace registry follow). Ships the shared session-store primitives (project-directory keys, jsonl.zstd frames, workspace registry, host/HTTP plumbing) as lib/store. One host entry with two HTTP prefixes and two model tools, one browser bundle with two right-pane tabs and a merged config card.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis-plugin",
+    "session",
+    "session-delete",
+    "session-move",
+    "session-store",
+    "housekeeping"
+  ],
+  "license": "MIT",
+  "author": "Cooper Zhuang",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./store": {
+      "default": "./lib/store/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "icon.svg",
+    "locale",
+    "docs"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=24",
+    "dsh": "^0.2.1-rc.2 || ^0.2.2-alpha.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5 || ^3.18.6-alpha.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5 || ^3.18.6-alpha.1"
+  },
+  "icon": "./icon.svg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CooperZhuang/dsh-plugins-cooper-custom.git",
+    "directory": "packages/dsh-session-ops"
+  },
+  "homepage": "https://github.com/CooperZhuang/dsh-plugins-cooper-custom/tree/main/packages/dsh-session-ops#readme",
+  "bugs": {
+    "url": "https://github.com/CooperZhuang/dsh-plugins-cooper-custom/issues"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-context-menu"
+      ],
+      "platform": "web"
+    }
+  }
+}