dsh-session-ops 0.1.4 → 0.2.0

package/lib/index.js

@@ -43,57 +43,24 @@
  *
  * @module dsh-session-ops
  */
-
-import z from '@deepseek-ai/schemastery'
-import {
-  LOG_LINE_LEVEL_FIRST,
-  LOG_LINE_TIME_FIRST,
-  createFileLogger,
-  resolveVolatileConfig,
-} from './store/host.js'
-import {
-  ADMIN_API_PREFIX,
-  createSessionAdmin,
-  isInside,
-  isTrustedRequest as isTrustedAdminRequest,
-  mountAdmin,
-} from './admin.js'
-import {
-  MOVE_API_PREFIX,
-  isTrustedRequest as isTrustedMoveRequest,
-  mountForkMembershipRepair,
-  mountMove,
-  sweepForkChildrenOnBoot,
-} from './move.js'
-
-export {
-  ADMIN_API_PREFIX,
-  MOVE_API_PREFIX,
-  createSessionAdmin,
-  isInside,
-  isTrustedAdminRequest,
-  isTrustedMoveRequest,
-  mountAdmin,
-  mountForkMembershipRepair,
-  mountMove,
-  sweepForkChildrenOnBoot,
-}
-
+import z from '@deepseek-ai/schemastery';
+import { LOG_LINE_LEVEL_FIRST, LOG_LINE_TIME_FIRST, createFileLogger, resolveVolatileConfig, } from './store/host.js';
+import { ADMIN_API_PREFIX, createSessionAdmin, isInside, isTrustedRequest as isTrustedAdminRequest, mountAdmin, } from './admin.js';
+import { MOVE_API_PREFIX, isTrustedRequest as isTrustedMoveRequest, mountForkMembershipRepair, mountMove, sweepForkChildrenOnBoot, } from './move.js';
+import { messageOf } from './store/util.js';
+export { ADMIN_API_PREFIX, MOVE_API_PREFIX, createSessionAdmin, isInside, isTrustedAdminRequest, isTrustedMoveRequest, mountAdmin, mountForkMembershipRepair, mountMove, sweepForkChildrenOnBoot, };
 /**
  * 搬迁半边原来的公开名（`dsh-session-move` 的 `API_PREFIX = '/session-move/api'`）。
  *
  * 合并后两半各有一个前缀，明确的名字是 {@link ADMIN_API_PREFIX} / {@link MOVE_API_PREFIX}；
  * 这个别名留着，是为了让按 `dsh-session-move/lib/index.js` 写过 import 的脚本/测试不改也能跑。
  */
-export const API_PREFIX = MOVE_API_PREFIX
-
+export const API_PREFIX = MOVE_API_PREFIX;
 // ---------------------------------------------------------------------------
 // 插件元信息
 // ---------------------------------------------------------------------------
-
 /** Cordis 插件名（profile 行 id 是 `session-toolbox`，两者刻意不同名）。 */
-export const name = 'dsh-session-ops'
-
+export const name = 'dsh-session-ops';
 /**
  * 依赖的服务。**这不是可选的**：cordis 里没有声明 inject 就拿不到服务，
  * `ctx.webServer` / `ctx.tools` / `ctx.sessions` / `ctx.sessionPersistence` 会静默是
@@ -103,15 +70,12 @@ export const name = 'dsh-session-ops'
  * `sessionPersistence`（会话根与写入句柄）。`workspaceRegistry` / `webServer` / `tools`
  * 两边都要。
  */
-export const inject = ['webServer', 'tools', 'sessions', 'sessionPersistence', 'workspaceRegistry']
-
+export const inject = ['webServer', 'tools', 'sessions', 'sessionPersistence', 'workspaceRegistry'];
 /** 设置命名空间；与 client 半边 `settings.section` 的 id 必须一致。 */
-export const SETTINGS_NS = 'session-toolbox'
-
+export const SETTINGS_NS = 'session-toolbox';
 // ---------------------------------------------------------------------------
 // 配置（两半合并成一份 schema）
 // ---------------------------------------------------------------------------
-
 /**
  * 插件配置（两份原配置的**并集**，键名与默认值见 {@link module:dsh-session-ops} 的表）。
  *
@@ -127,82 +91,81 @@ export const SETTINGS_NS = 'session-toolbox'
  * `description` 会随 schema 进入表单描述，是界面文案的权威来源。
  */
 export const Config = z.object({
-  /** 总开关（两半共用）。关掉后两条路由与两个工具都不注册。改它需要重挂本行（非 volatile）。 */
-  enabled: z.boolean().default(true),
-  /** 会话根目录；留空则从 `sessionPersistence.root` 推断（jsonl 后端会暴露它）。搬迁半边用。 */
-  root: z.string().default(''),
-  /**
-   * 删除半边的额外信任 authority（`host` 或 `host:port`，按 `Host` 头解析）。
-   * 原 `dsh-session-admin` 的 `allowHosts`。默认空——只信 loopback。
-   */
-  adminAllowHosts: z.array(String).default([]),
-  /**
-   * 搬迁半边的额外信任 authority（`host` 或 `host:port`，按 socket 的 `remoteAddress`
-   * 精确匹配）。原 `dsh-session-move` 的 `allowHosts`。默认空——只信 loopback。
-   */
-  moveAllowHosts: z.array(String).default([]),
-  /** 是否允许删「属于某个工作区」的会话。默认否——工作区会话通常还想留。 */
-  allowWorkspaceSessions: z.boolean().default(false)
-    .description('允许删除「属于某个工作区」的会话。默认否——工作区会话通常还想留。')
-    .volatile(),
-  /** 是否允许删仍然挂在 Host 进程里的会话（正在浏览/正在跑）。默认否。 */
-  allowLiveSessions: z.boolean().default(false)
-    .description('允许删除仍然挂在 Host 进程里的会话（正在浏览或正在跑）。默认否。')
-    .volatile(),
-  /** 一次调用最多删多少个，防手滑。 */
-  maxBatch: z.number().default(200)
-    .description('一次调用最多删多少个会话，防手滑。默认 200。')
-    .volatile(),
-  /**
-   * 是否在会话标题栏显示「删除当前会话」的垃圾桶图标。**默认开启。**
-   *
-   * 形态刻意是「图标 + 二次确认」而不是带字面标签的按钮：标签会招来点击，而这里
-   * 删的正是你正在用的会话。图标不占字面位置，误点最多弹出一个确认框，离真正删除
-   * 还隔着一步。清理由右侧「会话管理」面板或设置页承担，那是显式挑选动作。
-   *
-   * 这是个 volatile 旋钮：浏览器半边在挂载时问一次 Host（`config` 接口），所以
-   * 改完**刷新页面**就生效——不需要重启 dsh web，也不需要重挂本插件。
-   */
-  headerDeleteButton: z.boolean().default(true)
-    .description('在会话标题栏显示「删除当前会话」的垃圾桶图标。默认开启；关掉后清理由「会话管理」面板/设置页承担。改完刷新页面生效。')
-    .volatile(),
-  /** 是否拒绝搬"正在跑一轮"的会话。默认拒绝——搬运期间它的写入句柄可能落盘。 */
-  refuseRunning: z.boolean().default(true)
-    .description('拒绝搬迁「正在跑一轮」的会话。默认开启——搬运期间它的写入句柄可能落盘。')
-    .volatile(),
-  /** `list` 一次最多返回多少条会话（浏览器半边还要筛选）。 */
-  maxSessions: z.number().default(2000)
-    .description('`list` 一次最多返回多少条会话（浏览器半边还要筛选）。默认 2000。')
-    .volatile(),
-  /**
-   * 项目作用域记忆的条目要不要跟着会话走。**默认 off**。
-   *
-   * 项目记忆是**工作区共享**的（一次写入、那个工作区里所有会话都读），所以把一条
-   * 会话的条目拖到另一个工作区会改变那边的记忆视图——只有"这条会话本来就该在目标
-   * 工作区"（纠正错放）时才该这么做：
-   *   - `off`  ：什么都不做。报告里仍给出**只读预览**（若开启会复制哪几条）。
-   *   - `copy` ：把该会话产出的条目（frontmatter `session:` 精确匹配）复制到目标
-   *              工作区，按文件名去重，源工作区不动。
-   *   - `move` ：同上，但复制后从源工作区移除（不可逆，谨慎）。
-   */
-  memoryFollow: z.string().default('off')
-    .description('项目记忆跟随：off 只给只读预览（默认 / 推荐）；copy 把本会话产出的条目复制到目标工作区；move 复制后从源移除（不可逆）。')
-    .volatile(),
-  /**
-   * 启动时是否做一轮「fork 子会话漏挂工作区」的定向扫描。
-   *
-   * 创建期的 `session/created` 补挂只挡住「Host fork 时就没挂」。记账写进去之后
-   * 又被抹掉的那一类（同机两个 Host 共用 `$DSH_HOME` 时，另一个进程用旧内存快照
-   * 重写 `storages/workspace.json`）只有启动期扫描能补回来，所以默认开启。
-   *
-   * 扫描范围收得很窄：只认带 `parentSession` 的普通 fork 子会话（排除 `origin:
-   * subagent` 与 `delegationDepth > 0`），且父会话已被某个工作区记账、子会话
-   * `cwd` 规范化后等于该工作区路径。刻意 ungrouped 的普通会话/迁移会话不碰。
-   */
-  repairForkChildrenOnBoot: z.boolean().default(true)
-    .description('启动时补挂「fork 子会话漏挂工作区」：只处理父会话已入册、cwd 与工作区一致的普通 fork 子会话。默认开启；挂载期读取，改它需要重挂本行。'),
-})
-
+    /** 总开关（两半共用）。关掉后两条路由与两个工具都不注册。改它需要重挂本行（非 volatile）。 */
+    enabled: z.boolean().default(true),
+    /** 会话根目录；留空则从 `sessionPersistence.root` 推断（jsonl 后端会暴露它）。搬迁半边用。 */
+    root: z.string().default(''),
+    /**
+     * 删除半边的额外信任 authority（`host` 或 `host:port`，按 `Host` 头解析）。
+     * 原 `dsh-session-admin` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    adminAllowHosts: z.array(String).default([]),
+    /**
+     * 搬迁半边的额外信任 authority（`host` 或 `host:port`，按 socket 的 `remoteAddress`
+     * 精确匹配）。原 `dsh-session-move` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    moveAllowHosts: z.array(String).default([]),
+    /** 是否允许删「属于某个工作区」的会话。默认否——工作区会话通常还想留。 */
+    allowWorkspaceSessions: z.boolean().default(false)
+        .description('允许删除「属于某个工作区」的会话。默认否——工作区会话通常还想留。')
+        .volatile(),
+    /** 是否允许删仍然挂在 Host 进程里的会话（正在浏览/正在跑）。默认否。 */
+    allowLiveSessions: z.boolean().default(false)
+        .description('允许删除仍然挂在 Host 进程里的会话（正在浏览或正在跑）。默认否。')
+        .volatile(),
+    /** 一次调用最多删多少个，防手滑。 */
+    maxBatch: z.number().default(200)
+        .description('一次调用最多删多少个会话，防手滑。默认 200。')
+        .volatile(),
+    /**
+     * 是否在会话标题栏显示「删除当前会话」的垃圾桶图标。**默认开启。**
+     *
+     * 形态刻意是「图标 + 二次确认」而不是带字面标签的按钮：标签会招来点击，而这里
+     * 删的正是你正在用的会话。图标不占字面位置，误点最多弹出一个确认框，离真正删除
+     * 还隔着一步。清理由右侧「会话管理」面板或设置页承担，那是显式挑选动作。
+     *
+     * 这是个 volatile 旋钮：浏览器半边在挂载时问一次 Host（`config` 接口），所以
+     * 改完**刷新页面**就生效——不需要重启 dsh web，也不需要重挂本插件。
+     */
+    headerDeleteButton: z.boolean().default(true)
+        .description('在会话标题栏显示「删除当前会话」的垃圾桶图标。默认开启；关掉后清理由「会话管理」面板/设置页承担。改完刷新页面生效。')
+        .volatile(),
+    /** 是否拒绝搬"正在跑一轮"的会话。默认拒绝——搬运期间它的写入句柄可能落盘。 */
+    refuseRunning: z.boolean().default(true)
+        .description('拒绝搬迁「正在跑一轮」的会话。默认开启——搬运期间它的写入句柄可能落盘。')
+        .volatile(),
+    /** `list` 一次最多返回多少条会话（浏览器半边还要筛选）。 */
+    maxSessions: z.number().default(2000)
+        .description('`list` 一次最多返回多少条会话（浏览器半边还要筛选）。默认 2000。')
+        .volatile(),
+    /**
+     * 项目作用域记忆的条目要不要跟着会话走。**默认 off**。
+     *
+     * 项目记忆是**工作区共享**的（一次写入、那个工作区里所有会话都读），所以把一条
+     * 会话的条目拖到另一个工作区会改变那边的记忆视图——只有"这条会话本来就该在目标
+     * 工作区"（纠正错放）时才该这么做：
+     *   - `off`  ：什么都不做。报告里仍给出**只读预览**（若开启会复制哪几条）。
+     *   - `copy` ：把该会话产出的条目（frontmatter `session:` 精确匹配）复制到目标
+     *              工作区，按文件名去重，源工作区不动。
+     *   - `move` ：同上，但复制后从源工作区移除（不可逆，谨慎）。
+     */
+    memoryFollow: z.string().default('off')
+        .description('项目记忆跟随：off 只给只读预览（默认 / 推荐）；copy 把本会话产出的条目复制到目标工作区；move 复制后从源移除（不可逆）。')
+        .volatile(),
+    /**
+     * 启动时是否做一轮「fork 子会话漏挂工作区」的定向扫描。
+     *
+     * 创建期的 `session/created` 补挂只挡住「Host fork 时就没挂」。记账写进去之后
+     * 又被抹掉的那一类（同机两个 Host 共用 `$DSH_HOME` 时，另一个进程用旧内存快照
+     * 重写 `storages/workspace.json`）只有启动期扫描能补回来，所以默认开启。
+     *
+     * 扫描范围收得很窄：只认带 `parentSession` 的普通 fork 子会话（排除 `origin:
+     * subagent` 与 `delegationDepth > 0`），且父会话已被某个工作区记账、子会话
+     * `cwd` 规范化后等于该工作区路径。刻意 ungrouped 的普通会话/迁移会话不碰。
+     */
+    repairForkChildrenOnBoot: z.boolean().default(true)
+        .description('启动时补挂「fork 子会话漏挂工作区」：只处理父会话已入册、cwd 与工作区一致的普通 fork 子会话。默认开启；挂载期读取，改它需要重挂本行。'),
+});
 /**
  * 解包 entry 配置里的 `.volatile()` 活引用，并交给 schema 校验补默认值。
  *
@@ -213,13 +176,10 @@ export const Config = z.object({
  * @returns 普通值配置。
  */
 export function resolveConfig(raw = {}) {
-  return resolveVolatileConfig(Config, raw)
+    // 解包后的普通对象在这里收敛成 {@link SessionOpsConfig}：schema 的默认值保证了
+    // 每个键都在，但 schemastery 的输出类型不携带这些静态事实，只能就地断言一次。
+    return resolveVolatileConfig(Config, raw);
 }
-
-// ---------------------------------------------------------------------------
-// 插件入口
-// ---------------------------------------------------------------------------
-
 /**
  * 挂载插件：两条路由 + 两个工具。
  *
@@ -234,47 +194,47 @@ export function resolveConfig(raw = {}) {
  * @param rawConfig - 部署层配置。
  * @returns 无。
  */
-export function apply(ctx, rawConfig) {
-  /**
-   * 当前生效的配置。
-   *
-   * 对象**身份保持不变**：volatile 字段更新时只把新值 `Object.assign` 进来，于是两个
-   * 半边里所有已经捕获了 `config` 的闭包（HTTP 方法表、工具、信任栅栏、日志）自动
-   * 看到最新值，不需要重挂，也不需要额外的 getter 管道。
-   */
-  const config = { ...resolveConfig(rawConfig) }
-  // 两个半边各自的文件日志（行格式是各自原有的排障产物，见 lib/store/host.js）。
-  const adminLog = createFileLogger(ctx, { name: 'dsh-session-admin', formatLine: LOG_LINE_LEVEL_FIRST })
-  const moveLog = createFileLogger(ctx, { name: 'dsh-session-move', formatLine: LOG_LINE_TIME_FIRST })
-  const logs = [adminLog, moveLog]
-  // volatile 字段写盘后 Loader 原地换引用并补发这个事件：重读一次就能拿到新值。
-  ctx.on('loader/volatile-update', () => {
-    try {
-      Object.assign(config, resolveConfig(rawConfig))
-    } catch (error) {
-      // 表单写盘前会先校验候选值，正常路径不会走到这里；真出错也不能把插件带崩。
-      for (const log of logs) log('warn', `config refresh failed: ${String(error)}`)
+export function apply(ctx, rawConfig = {}) {
+    /**
+     * 当前生效的配置。
+     *
+     * 对象**身份保持不变**：volatile 字段更新时只把新值 `Object.assign` 进来，于是两个
+     * 半边里所有已经捕获了 `config` 的闭包（HTTP 方法表、工具、信任栅栏、日志）自动
+     * 看到最新值，不需要重挂，也不需要额外的 getter 管道。
+     */
+    const config = { ...resolveConfig(rawConfig) };
+    // 两个半边各自的文件日志（行格式是各自原有的排障产物，见 lib/store/host.js）。
+    const adminLog = createFileLogger(ctx, { name: 'dsh-session-admin', formatLine: LOG_LINE_LEVEL_FIRST });
+    const moveLog = createFileLogger(ctx, { name: 'dsh-session-move', formatLine: LOG_LINE_TIME_FIRST });
+    const logs = [adminLog, moveLog];
+    // volatile 字段写盘后 Loader 原地换引用并补发这个事件：重读一次就能拿到新值。
+    ctx.on('loader/volatile-update', () => {
+        try {
+            Object.assign(config, resolveConfig(rawConfig));
+        }
+        catch (error) {
+            // 表单写盘前会先校验候选值，正常路径不会走到这里；真出错也不能把插件带崩。
+            for (const log of logs)
+                log('warn', `config refresh failed: ${String(error)}`);
+        }
+    });
+    if (config.enabled === false) {
+        for (const log of logs)
+            log('info', 'disabled by config; nothing registered');
+        return;
+    }
+    mountAdmin(ctx, config, adminLog);
+    mountMove(ctx, config, moveLog);
+    // fork 子会话漏挂工作区（实测）：创建期监听 + 启动期定向扫描；只补记账，不改 Host 源码。
+    // 扫描是 fire-and-forget，但绝不留下未处理的 rejection——自愈路径不能影响插件其余部分。
+    const forkSweep = mountForkMembershipRepair(ctx, config, moveLog);
+    if (forkSweep !== undefined) {
+        forkSweep.catch((error) => moveLog('warn', `membership sweep failed: ${messageOf(error)}`));
     }
-  })
-  if (config.enabled === false) {
-    for (const log of logs) log('info', 'disabled by config; nothing registered')
-    return
-  }
-
-  mountAdmin(ctx, config, adminLog)
-  mountMove(ctx, config, moveLog)
-  // fork 子会话漏挂工作区（实测）：创建期监听 + 启动期定向扫描；只补记账，不改 Host 源码。
-  // 扫描是 fire-and-forget，但绝不留下未处理的 rejection——自愈路径不能影响插件其余部分。
-  const forkSweep = mountForkMembershipRepair(ctx, config, moveLog)
-  if (forkSweep !== undefined) {
-    forkSweep.catch((error) => moveLog('warn', `membership sweep failed: ${String(error?.message ?? error)}`))
-  }
 }
-
 // ---------------------------------------------------------------------------
 // 兼容再导出
 // ---------------------------------------------------------------------------
-
 /**
  * 会话存储原语全量再导出（`lib/store/` 的五个模块）：
  * `dshHome`、`encodeSegment`、`readSessionHeader`、`hasZstd`、`decodeProjectKey` 等。
@@ -283,7 +243,6 @@ export function apply(ctx, rawConfig) {
  * 外部按包名导入的脚本（如 dsh-open-in-dsh）只改包名即可，不必换符号名。
  * 需要显式分层时也可以用子路径 `dsh-session-ops/store`（见 package.json exports）。
  */
-export * from './store/index.js'
-
+export * from './store/index.js';
 // 2026-09-25：本文件是 dsh-session-admin + dsh-session-move 的合并入口
 // （本包就是这两个插件的合并产物；会话存储知识收在 `lib/store/`）。