dsh-session-ops 0.0.0-stage → 0.2.0

package/lib/store/paths.js

@@ -0,0 +1,166 @@
+/**
+ * 会话存储的**路径命名**知识：项目目录键（`--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';
+import { messageOf } from './util.js';
+/** 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}: ${messageOf(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,234 @@
+/**
+ * 会话**归属**知识：工作区注册表（`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`，界面照常显示）。
+ *
+ * 这里声明的都是**最小本地接口**：Cordis/DSH 的宿主对象在编译期拿不到类型，
+ * 但本模块只用到这几个字段，把它们写清楚比整片 `any` 更能挡住拼写错误。
+ *
+ * @module dsh-session-ops/store/registry
+ */
+import { messageOf } from './util.js';
+/** 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 = messageOf(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/lib/store/util.js

@@ -0,0 +1,19 @@
+/**
+ * 本包内部的小工具：只放「宿主边界上重复出现、但语义必须逐字一致」的那几行。
+ *
+ * 目前只有一处：把 `unknown` 类型抛出的错误取成可读文案。JS 里的写法是
+ * `String(error?.message ?? error)`——它同时容忍 Error、任意带 `message` 的对象、
+ * 以及 `throw 'oops'` 这样的原始值。TS 的 `catch` 变量是 `unknown`，这份语义必须
+ * 原样保留（错误文案会被用户可见的报告与日志引用），所以收成一个函数。
+ *
+ * @module dsh-session-ops/store/util
+ */
+/**
+ * 取一个 unknown 错误的可读文案，语义与 `String(error?.message ?? error)` 逐字一致。
+ * @param error - catch 到的错误。
+ * @returns 可读文案。
+ */
+export function messageOf(error) {
+    const candidate = error;
+    return String(candidate?.message ?? error);
+}

package/lib/types/admin.d.ts

@@ -0,0 +1,187 @@
+/**
+ * `dsh-session-ops` 的**删除半边**（原 `dsh-session-admin` 插件的 Host 半边）。
+ *
+ * 这一半的代码搬自原 `dsh-session-admin` 的 `lib/index.js`，只有四处差异：
+ *   - 插件 entry 的 `name` / `inject` / `SETTINGS_NS` / `Config` / `resolveConfig` / `apply`
+ *     上移到 `lib/index.js`——合并后的包只有一个 entry、一份配置 schema、一个 `apply`；
+ *   - `API_PREFIX` 改名 `ADMIN_API_PREFIX`（搬迁半边占着 `MOVE_API_PREFIX`）；
+ *   - 配置键 `allowHosts` 改名 `adminAllowHosts`（两半的信任栅栏语义不同，见 `lib/index.js`）；
+ *   - 原 `apply` 里"建配置/建日志/订阅 volatile/看 enabled"那段上移到入口，剩下的接线
+ *     成为 `mountAdmin(ctx, config, log)`。
+ * 其余一字未动：扫描与范围筛选、逐条守卫、`/session-admin/api` 的方法表、
+ * `session_admin` 工具定义、Host 头版信任栅栏，连注释都保持原样。
+ *
+ * 能力：把会话的持久化数据真正从磁盘移除。一个会话在磁盘上最多占三处：
+ *   - `<home>/sessions/<项目目录键>/<session-id>/`   ← 会话日志（jsonl.zstd）
+ *   - `<home>/storages/session_projcache/sessions/<session-id>.json` ← 投影缓存
+ *   - `<home>/rewind-snapshots/<session-id>/`        ← 回退快照（可有可无）
+ * 三处一起删，并顺手清掉因此变空的项目目录。
+ *
+ * 刻意零 `@deepseek-ai/*` 运行时依赖：只用 Node 内置模块和一份 schemastery 配置
+ * schema。工具注册用普通对象（与 `dsh-subagent-in-process-driver` 同款），不做
+ * `defineTool` 导入——profile 的 node_modules 里未必解析得到 `@deepseek-ai/dsh-tools`。
+ * 代价是 `parameters` / `output.schema` 都必须自己写成**已编译的 JSON Schema**：
+ * register 不做编译，只把对象原样透传给 provider（详见 `TOOL_PARAMETERS` 注释）。
+ *
+ * @module dsh-session-ops/admin
+ */
+import { dshHome } from './store/host.js';
+import type { LogFn } from './store/host.js';
+import type { HttpRequest } from './store/http.js';
+import { decodeProjectKey } from './store/paths.js';
+import type { WorkspaceRegistryLike } from './store/registry.js';
+import type { SessionOpsConfig } from './index.js';
+/** HTTP 路由前缀（两半各一条，合并后仍然分开）。 */
+export declare const ADMIN_API_PREFIX = "/session-admin/api";
+/**
+ * `$DSH_HOME`（环境变量优先，默认 `~/.dsh`）。
+ *
+ * 实现在 `lib/store/host.js`——它与搬迁半边用的是同一份；
+ * 这里再导出，保持本仓库的公开面不变。
+ */
+export { dshHome };
+/**
+ * 把 `sessions/` 下的项目目录键还原成路径。
+ *
+ * 实现在 `lib/store/paths.js`：它与搬迁半边的 `projectKey`
+ * 是同一套规则的两个方向，规则只该有一份。这里再导出，保持本仓库的公开面不变。
+ */
+export { decodeProjectKey };
+/** 路径是否落在某个根目录内部（防目录穿越）。 */
+export declare function isInside(root: string, candidate: string): boolean;
+/** 扫描出来的一条会话记录。 */
+export interface SessionRecord {
+    id: string;
+    dir: string;
+    project: string;
+    cwd: string | null;
+    title: string | null;
+    origin: string | null;
+    parentSessionId: string | null;
+    isSeeded: boolean | null;
+    headerReadable: boolean;
+    workspaceId: string | null;
+    workspaceTitle: string | null;
+    ungrouped: boolean;
+    archived: boolean;
+    subagent: boolean;
+    cwdMissing: boolean;
+    temp: boolean;
+    bytes: number;
+    files: number;
+    updatedAt: number;
+    hasProjCache: boolean;
+    hasRewind: boolean;
+}
+/** {@link SessionAdmin.scan} 的选项。 */
+export interface ScanOptions {
+    /** `false` 跳过逐会话的体积统计（只要个数的调用方用它压开销）。 */
+    measure?: boolean;
+}
+/** {@link SessionAdmin.select} 的范围查询。 */
+export interface SelectQuery {
+    scope?: string;
+    cwdPrefix?: string;
+    search?: string;
+}
+/** {@link SessionAdmin.remove} 的选项。 */
+export interface RemoveOptions {
+    dryRun?: boolean;
+    includeWorkspace?: boolean;
+    includeArchived?: boolean;
+    includeSubagent?: boolean;
+    includeLive?: boolean;
+    /** **正在跑**、因此现在不能删的 id 集合。 */
+    live?: Set<string>;
+    callerSessionId?: string;
+    maxBatch?: number;
+}
+/** {@link SessionAdmin.remove} 里逐条的结果。 */
+export interface RemoveResult {
+    id: string;
+    status: 'skipped' | 'would-remove' | 'failed' | 'removed';
+    reason?: string;
+    bytes?: number;
+}
+/** {@link SessionAdmin.remove} 的汇总。 */
+export interface RemoveReport {
+    /** 早退（目标集合为空）时这个键不存在——与改动前的返回形状一致。 */
+    dryRun?: boolean;
+    removed: number;
+    reclaimed: number;
+    pruned: string[];
+    results: RemoveResult[];
+}
+/** {@link createSessionAdmin} 的选项。 */
+export interface CreateSessionAdminOptions {
+    /** DSH 主目录（默认 `dshHome()`）。 */
+    home?: string;
+    /** 视为「临时目录」的前缀。 */
+    tempRoots?: string[];
+    /** 删文件**之前**把一个会话从登记表里摘掉的异步回调。 */
+    releaseSession?: (sessionId: string) => Promise<unknown>;
+}
+/** 会话管理员（扫描 / 过滤 / 删除三个入口）。 */
+export interface SessionAdmin {
+    home: string;
+    sessionsRoot: string;
+    projcacheRoot: string;
+    rewindRoot: string;
+    scan(options?: ScanOptions): SessionRecord[];
+    select(records: SessionRecord[], query?: SelectQuery): SessionRecord[];
+    remove(ids: string[], options?: RemoveOptions): Promise<RemoveReport>;
+}
+/**
+ * 构造一个会话管理员。所有根目录都可注入，便于在测试里指向沙箱。
+ * @param options - `home`（DSH 主目录）、`tempRoots`（视为「临时目录」的前缀）、
+ *   `releaseSession`（删文件**之前**把一个会话从登记表里摘掉的异步回调；见 `remove`）。
+ * @returns 扫描 / 过滤 / 删除三个入口。
+ */
+export declare function createSessionAdmin(options?: CreateSessionAdminOptions): SessionAdmin;
+/**
+ * 判断一个请求是否有权访问本插件的路由。
+ *
+ * 本机 `dsh web` 常被绑到 `0.0.0.0`（局域网访问），所以「能连上端口」不等于
+ * 「是这台机器上的人」：非回环 authority 默认一律拒绝，除非在配置的
+ * `allowHosts` 里显式列出。同时拒绝 `sec-fetch-site: cross-site` 和跨源 Origin。
+ *
+ * **这份栅栏刻意留在本仓库**：`dsh-session-move` 那份按 socket 的 `remoteAddress`
+ * 判断回环、`allowHosts` 只做精确字符串匹配，既不解析 authority 也不看
+ * `sec-fetch-site`/`Origin`——两边语义不同，合并必然改掉其中一边的对外行为。
+ * 共享包只提供路由骨架（`createApiHandler`），栅栏以回调形式传进去。
+ * @param req - Node HTTP 请求。
+ * @param allowHosts - 额外信任的 authority 列表。
+ * @returns 是否放行。
+ */
+export declare function isTrustedRequest(req: HttpRequest, allowHosts?: string[]): boolean;
+/**
+ * Host cordis 上下文里删除半边用到的那部分（最小本地接口，见 `src/index.ts` 的说明）。
+ */
+export interface AdminContext {
+    logger?: Record<string, ((message: string) => unknown) | undefined> | undefined;
+    effect: (fn: () => unknown, label?: string) => unknown;
+    get: (name: string) => any;
+    webServer: {
+        register(options: unknown): unknown;
+    };
+    tools: {
+        register(definition: unknown): unknown;
+    };
+    workspaceRegistry: WorkspaceRegistryLike;
+}
+/**
+ * 挂载删除半边：路由 + 工具。
+ *
+ * 与搬迁半边刻意不同的三点（原样保留的理由）：
+ *   - 信任栅栏按 `Host` 头判断（`isTrustedRequest`），额外拒绝 `sec-fetch-site: cross-site`
+ *     与跨源 `Origin`；搬迁半边看 socket 的 `remoteAddress`；
+ *   - 响应带 `content-length`；
+ *   - 请求体按**宽松模式**读（空白 body 走 `JSON.parse` 报错，非对象不拦）。
+ *
+ * @param ctx - Host cordis 上下文（`webServer` / `tools` / `sessions` / `workspaceRegistry`）。
+ * @param config - 已解包的**活配置对象**：身份由入口保持，volatile 更新时原地覆盖，
+ *   所以下面这些闭包自动看到最新值。
+ * @param log - `(level, message) => void`（入口传的是 admin 那套行格式的文件日志）。
+ * @returns 无。
+ */
+export declare function mountAdmin(ctx: AdminContext, config: SessionOpsConfig, log: LogFn): void;