dsh-session-ops 0.0.0-stage → 0.2.0

package/lib/types/move.d.ts

@@ -0,0 +1,272 @@
+/**
+ * `dsh-session-ops` 的**搬迁半边**（原 `dsh-session-move` 插件的 Host 半边）。
+ *
+ * 这一半的代码搬自原 `dsh-session-move` 的 `lib/index.js`，差异只有四处：
+ *   - 插件 entry 的 `name` / `inject` / `Config` / `resolveConfig` / `apply` 上移到
+ *     `lib/index.js`（合并后只有一个 entry、一份配置 schema、一个 `apply`）；
+ *   - `API_PREFIX` 改名 `MOVE_API_PREFIX`（删除半边占着 `ADMIN_API_PREFIX`）；
+ *   - 配置键 `allowHosts` 改名 `moveAllowHosts`（与 `adminAllowHosts` 语义不同）；
+ *   - 原 `apply` 里"建配置/建日志/订阅 volatile/看 enabled"那段上移到入口，剩下的接线
+ *     成为 `mountMove(ctx, config, log)`。
+ * 其余一字未动（`createMover`、`/session-move/api` 的方法表、`session_move` 工具定义、
+ * socket 版信任栅栏、注释）。`./engine.js` / `./memory.js` / `./sessionlog.js` 也原样搬来。
+ *
+ * 能力：把一条已持久化的会话搬到另一个工作区——**真搬迁**：
+ *   1. 会话日志搬到目标工作区的 project 目录，header 的 `cwd` 改写成目标路径；
+ *   2. 目标工作区 `attachSession`、原工作区 `detachSession`（工作区注册表成员随动）；
+ *   3. 若该会话此刻正被 Host 持有（`ctx.sessions` 里挂着），同时改写内存里的
+ *      `session.header.cwd` 与持久化写入句柄的 header，让它之后继续往新位置写。
+ *
+ * 一处硬边界：**正在跑一轮的会话一律拒绝**（`refuseRunning` 默认 true）。它的写入句柄
+ * 随时可能落盘，搬家窗口里挪目录会让这一轮的事件写到一个不存在的位置（ENOENT）。
+ *
+ * 会话存储的公共知识（路径命名、帧读写、注册表成员/归档集合、「正在跑」判定、
+ * 宿主与 HTTP 面的底座）在 `lib/store/` 里；本文件只保留搬迁策略本身。
+ *
+ * @module dsh-session-ops/move
+ */
+import type { HttpRequest } from './store/http.js';
+import { dshHome } from './store/host.js';
+import type { LogFn } from './store/host.js';
+import type { PersistenceLike, WorkspaceEntity, WorkspaceRegistryLike } from './store/registry.js';
+import type { MoveReport } from './engine.js';
+import type { MemoryFollowOutcome } from './memory.js';
+import type { SessionOpsConfig } from './index.js';
+/** HTTP 路由前缀（两半各一条，合并后仍然分开）。 */
+export declare const MOVE_API_PREFIX = "/session-move/api";
+/**
+ * `$DSH_HOME`（环境变量优先，默认 `~/.dsh`）。
+ *
+ * 实现在 `lib/store/host.js`——它与删除半边用的是同一份；
+ * 这里再导出，保持本仓库的公开面不变。
+ */
+export { dshHome };
+/**
+ * loopback 或显式白名单 authority 才放行，并额外拒绝浏览器侧的跨站 / 跨源请求。
+ *
+ * 原先这份栅栏只按 socket 的 `remoteAddress` 判断回环、`allowHosts` 只做精确字符串
+ * 匹配，**不看 `sec-fetch-site` / `Origin`**——恶意页面从任意站点 POST 到本机
+ * `127.0.0.1:3080` 时，socket 地址同样是回环，只看 `remoteAddress` 拦不住。
+ * 2026-09-25 与 `dsh-session-admin` 那份栅栏对齐（那条缺口已补），差异只剩
+ * 「本份以 `remoteAddress` 为回环判据、admin 以 `Host` 头为判据」。
+ * 共享包只提供路由骨架（`createApiHandler`），栅栏以回调形式传进去。
+ */
+export declare function isTrustedRequest(req: HttpRequest, allowHosts: string[]): boolean;
+/** 持久化后端 `list()` 返回的一条会话快照。 */
+export interface SessionSnapshotLike {
+    id?: unknown;
+    header: Record<string, unknown>;
+}
+/** 持久化后端 `open()` 返回的读句柄。 */
+export interface PersistenceHandleLike {
+    header: Record<string, unknown>;
+    inheritedEventCount?: unknown;
+    read(): Promise<{
+        events?: unknown[];
+    } | undefined>;
+    close(): Promise<unknown>;
+}
+/** 搬迁半边用到的持久化后端能力（`ctx.sessionPersistence` 的子集）。 */
+export interface SessionPersistenceLike extends PersistenceLike {
+    list: () => Promise<SessionSnapshotLike[]>;
+    open: (sessionId: string, mode: string) => Promise<PersistenceHandleLike>;
+}
+/** `list` 快照里的一行工作区。 */
+export interface WorkspaceSummary {
+    id: string;
+    title: string;
+    path: string;
+    visible: number;
+    accounted: number;
+}
+/** `list` 快照里的一条会话。 */
+export interface SessionRow {
+    id: string;
+    cwd: string | null;
+    createdAt: number | null;
+    resident: boolean;
+    running: string | null;
+    hasWriteHandle: boolean;
+    archived: boolean;
+    workspaceId: string | null;
+    workspaceTitle: string | null;
+    movable: boolean;
+}
+/** {@link Mover.list} 的返回。 */
+export interface ListSnapshot {
+    root: string;
+    compression: string;
+    zstd: boolean;
+    workspaces: WorkspaceSummary[];
+    sessions: SessionRow[];
+    counts: {
+        stored: number;
+        resident: number;
+        workspaces: number;
+    };
+}
+/** `mover.move` 的入参（HTTP / 工具都把浏览器或模型给的对象原样递进来）。 */
+export interface MoveRequest {
+    sessionId?: unknown;
+    targetWorkspace?: unknown;
+    dryRun?: unknown;
+}
+/** 计划摘要在报告里的形状。 */
+export interface MovePlanSummary {
+    generation: string;
+    version: number;
+    compressed: boolean;
+    bytesBefore: number;
+    bytesAfter: number;
+    frames: number | null;
+    sourcePath: string;
+    targetPath: string;
+    leaseFile: string | null;
+    leftInSourceDir: string[];
+    otherGenerations: string[];
+}
+/** 记忆跟随预览/结果摘要在报告里的形状。 */
+export interface MemoryFollowSummary {
+    mode: string;
+    sourceSlug?: string | null;
+    targetSlug?: string;
+    targetHadProject?: boolean;
+    sourceEntries?: number;
+    matched?: number;
+    titles?: string[];
+    alreadyInTarget?: number;
+    note?: string;
+    error?: string;
+    applied?: MemoryFollowOutcome;
+    applyError?: string;
+}
+/** `mover.verify` 的读回结果。 */
+export interface VerifyReadback {
+    headerCwd: string | null;
+    inheritedEventCount: number;
+    events: number | null;
+}
+/** {@link Mover.move} 的完整报告。字段按路径可选（noop / attach-only / dry-run）。 */
+export interface MoveActionReport {
+    sessionId: string;
+    from: string;
+    to: string;
+    workspace: {
+        id: string;
+        title: string;
+    };
+    dryRun: boolean;
+    running: string | null;
+    noop?: boolean;
+    note?: string;
+    attachOnly?: boolean;
+    dryRunOnly?: boolean;
+    plan?: MovePlanSummary;
+    memoryFollow?: MemoryFollowSummary;
+    storage?: MoveReport;
+    handleFlushError?: string;
+    writeHandleRedirected?: boolean;
+    liveHeaderUpdated?: boolean;
+    registryHeaderCacheUpdated?: boolean;
+    attachedTo?: string;
+    detachedFrom?: string;
+    detachError?: string;
+    dshReadback?: VerifyReadback;
+    dshReadbackError?: string;
+    memoryScope?: string;
+    ok?: boolean;
+}
+/** `list` / `move` / `verify` 三个入口（`createMover` 的返回）。 */
+export interface Mover {
+    list: () => Promise<ListSnapshot>;
+    move: (request: MoveRequest) => Promise<MoveActionReport>;
+    verify: (sessionId: string) => Promise<VerifyReadback>;
+    rootOf: () => string;
+    compressionOf: () => string;
+    resolveWorkspace: (key: unknown) => WorkspaceEntity | undefined;
+}
+/** {@link createMover} 用到的 Host 上下文（最小本地接口，见 `src/index.ts` 的说明）。 */
+export interface MoveContext {
+    sessionPersistence?: SessionPersistenceLike | undefined;
+    workspaceRegistry: WorkspaceRegistryLike;
+    get: (name: string) => any;
+    webServer: {
+        register(options: unknown): unknown;
+    };
+    tools: {
+        register(definition: unknown): unknown;
+    };
+    effect: (fn: () => unknown, label?: string) => unknown;
+}
+/**
+ * 挂载搬迁半边：路由 + 工具。
+ *
+ * 与删除半边刻意不同的两点（原样保留的理由）：
+ *   - 信任栅栏看 socket 的 `remoteAddress`（`isTrustedRequest`），`allowHosts` 只做精确
+ *     字符串匹配；删除半边看 `Host` 头；
+ *   - 请求体按**严格模式**读（`requireObject: true`，非普通对象一律 400）。
+ *
+ * @param ctx - Host cordis 上下文（`webServer` / `tools` / `sessionPersistence` /
+ *   `workspaceRegistry`；`sessions` / `agents` 是可选事实源，用 `ctx.get` 取）。
+ * @param config - 已解包的**活配置对象**（身份由入口保持，volatile 更新时原地覆盖）。
+ * @param log - `(level, message) => void`（入口传的是 move 那套行格式的文件日志）。
+ * @returns 无。
+ */
+export declare function mountMove(ctx: MoveContext, config: SessionOpsConfig, log: LogFn): void;
+/** 成员自愈扫描的汇总。 */
+export interface ForkSweepReport {
+    checked: number;
+    attached: number;
+    skipped?: string;
+}
+/** 成员自愈器（创建期监听与启动期扫描共用）。 */
+export interface ForkMembershipRepairer {
+    repair: (sessionId: string, header: Record<string, unknown> | undefined, reason: string) => Promise<void>;
+    ownerOf: (sessionId: string) => WorkspaceEntity | undefined;
+}
+/**
+ * 成员自愈用到的 Host 上下文（`workspaceRegistry` 可缺：缺了就跳过自愈）。
+ */
+export interface RepairContext {
+    workspaceRegistry?: WorkspaceRegistryLike | undefined;
+    sessionPersistence?: SessionPersistenceLike | undefined;
+    on: (event: string, handler: (...args: any[]) => unknown) => unknown;
+}
+/**
+ * 启动期的成员自愈扫描：把**已经丢掉记账**的 fork 子会话补回去。
+ *
+ * ## 为什么创建期补挂不够（实测的第二条证据链）
+ *
+ * `session/created` 那一刻补挂只挡住「Host fork 时就没挂」这一种。实测中有些 fork
+ * 在 Host 侧确实走了 `workspace.attachSession(childId)`（RPC 返回成功、插件侧没有
+ * `fork 失败` 日志），但子会话最终仍不在任何工作区的 `sessionIds` 里——也就是说
+ * 记账**写进去之后又没了**。同一个时间窗里，父会话的归档也没落住。
+ *
+ * 能同时抹掉「新 attach」与「归档集合」的只有一件事：**另一个 Host 进程用自己内存里
+ * 的旧快照重写了 `$DSH_HOME/storages/workspace.json`**。存储层是整文件原子替换、
+ * 无跨进程锁（`dsh-storage-json` 的注释写的就是「一个 unit 文件只有一个写者，后写
+ * 覆盖先写是对的」），而同一台机器上同时跑两个 Host、共用同一个 `~/.dsh` 就会出现
+ * 这类丢失。这类丢失发生在 attach 之后，创建期的补挂拦不住。
+ *
+ * 所以这里补一道**启动期**的定向扫描：只处理 fork 子会话（`isForkChild`），且仍然
+ * 要求「父会话已被工作区记账 + 子会话 cwd 规范化后等于该工作区路径」；不碰子代理、
+ * 不碰没有父会话的普通会话，也不做全量 attach，避免改写用户刻意留着的 ungrouped。
+ *
+ * 幂等：已记账直接跳过；失败只记日志，绝不让插件挂载失败。
+ *
+ * @param ctx - Host cordis 上下文（需要 `workspaceRegistry` 与 `sessionPersistence`）。
+ * @param config - 活配置对象；`repairForkChildrenOnBoot === false` 时跳过整轮扫描。
+ * @param log - `(level, message) => void`。
+ * @param shared - 与创建期监听器共享的 repairer（`mountForkMembershipRepair` 内部用）。
+ * @returns 扫描结束（含跳过）后 resolve 的报告；永不 reject。
+ */
+export declare function sweepForkChildrenOnBoot(ctx: RepairContext, config?: Partial<SessionOpsConfig>, log?: LogFn, shared?: ForkMembershipRepairer): Promise<ForkSweepReport>;
+/**
+ * 挂载 fork 子会话的成员自愈：创建期监听 + 启动期定向扫描。
+ *
+ * @param ctx - Host cordis 上下文。
+ * @param config - 活配置对象。
+ * @param log - `(level, message) => void`。
+ * @returns 启动期扫描的 Promise（Host/cordis 忽略；测试可 await 以确定性观察结果）。
+ */
+export declare function mountForkMembershipRepair(ctx: RepairContext, config: Partial<SessionOpsConfig>, log: LogFn): Promise<ForkSweepReport> | undefined;

package/lib/types/sessionlog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 会话日志的帧级读写原语 —— **实现在本包的 `lib/store/` 里**（`dsh-session-ops`）。
+ *
+ * 这个文件现在只是一层**历史路径的门面**：`./sessionlog.js` 曾经是本插件私有的
+ * 实现（从 dsh-sync 移植），而删除半边那边重复着同一套知识的另一半
+ * （`decodeProjectKey`）。两个插件合并成 `dsh-session-ops` 之后：
+ *   - 实现只有一份，规则与边界都写在 `lib/store/paths.js` / `lib/store/frames.js`
+ *     的模块注释里；
+ *   - 这里的模块路径保留下来，是为了让本包原有的 `test/*.mjs` 不必改 import 就继续可用。
+ *
+ * @module dsh-session-ops/sessionlog
+ */
+export { CHECKSUM_OPTIONS, ZSTD_MAGIC, hasZstd, readHeaderFromBuffer, rewriteHeaderCwd, scanZstdFrames, } from './store/frames.js';
+export { compressionSuffix, encodeSegment, generationLogFilename, logPath, projectKey, sessionDir, } from './store/paths.js';

package/lib/types/store/frames.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 会话日志（`session[.vN].jsonl[.zstd]`）的**帧级读写原语**。
+ *
+ * ## 帧格式
+ *
+ * 日志是**独立 Zstandard 帧的标准拼接**：帧 0 只含 header 行（DSH 的
+ * `assertIndependentHeaderFrame` 强制），之后每帧是一个事件批次。于是改写只需重压
+ * 帧 0、再把剩余字节原样接上——后续帧一个字节都不动。
+ *
+ * 两个必须对齐的细节：
+ *   - DSH 压缩时带内容校验和（`params: {[ZSTD_c_checksumFlag]: 1}`），重压帧 0
+ *     也必须带（见 {@link CHECKSUM_OPTIONS}）；
+ *   - 帧边界要自己走一遍（Node 不暴露「已消费输入字节数」），就是下面的
+ *     {@link scanZstdFrames}。
+ *
+ * ## 为什么头部这么要紧
+ *
+ * header 承载 `cwd` / `origin` / `parentSession` / `isSeeded`：
+ *   - 「会话属于哪个工作区」在 DSH 里**只**由 `header.cwd` 决定
+ *     （`WorkspaceEntity.sessionIds` 每次读取都用 `realpath(header.cwd) === workspace.path`
+ *     过滤），加上 `assertStoredIdentity` 要求物理路径等于
+ *     `logPath(root, header.cwd, id)`，所以搬迁 == 改 cwd + 挪目录；
+ *   - 「是不是子代理会话」只能从 `origin` 拿，projcache 里没有。
+ *
+ * 于是本模块同时提供两种读法，**语义不同、不要互相替换**：
+ *   - {@link readHeaderFromBuffer}：只解**帧 0**（帧结构严格，给搬迁用）；
+ *   - {@link readSessionHeader}：按目录找日志文件、整段解压取第一行（宽松，给扫描/删除用）。
+ *
+ * @module dsh-session-ops/store/frames
+ */
+/** zstd 帧魔数（小端）。 */
+export declare const ZSTD_MAGIC = 4247762216;
+/** zstd 压缩选项（带内容校验和时才有 `params`）。 */
+export interface ZstdCompressOptions {
+    params?: Record<number, number>;
+}
+/** 与 DSH 一致的压缩选项：带内容校验和。 */
+export declare const CHECKSUM_OPTIONS: ZstdCompressOptions;
+/** `zstdCompressSync` 需要 Node ≥22.15 / ≥23.8；缺失时插件拒绝搬迁而不是写坏日志。 */
+export declare const hasZstd: boolean;
+/** 会话头（日志第一行）。字段按 DSH 实际写入的形状声明，其余键原样保留。 */
+export interface SessionHeader {
+    type?: string;
+    version?: number;
+    id?: string;
+    cwd?: string;
+    origin?: string;
+    parentSession?: string;
+    isSeeded?: boolean;
+    delegationDepth?: number;
+    createdAt?: number;
+    [key: string]: unknown;
+}
+/** 拼接帧里的一个帧范围。 */
+export interface ZstdFrameRange {
+    start: number;
+    end: number;
+}
+/** {@link scanZstdFrames} 的扫描结果。 */
+export interface ZstdFrameScan {
+    frames: ZstdFrameRange[];
+    incomplete: boolean;
+    reason?: string;
+}
+/**
+ * 走一遍拼接帧，给出每帧的字节范围。
+ *
+ * 按 zstd 规范解析帧头（魔数 → Frame_Header_Descriptor → 可选窗口描述符 /
+ * 字典 id / 内容长度）与块序列（3 字节块头 → 块体），直到 Last_Block，
+ * 再按标志位跳过 4 字节内容校验和。
+ *
+ * @param buffer - 整个日志文件的内容。
+ * @returns `{frames, incomplete, reason}`；`frames` 每项含 `{start, end}`。
+ */
+export declare function scanZstdFrames(buffer: Buffer): ZstdFrameScan;
+/**
+ * 读出日志第一帧里的 header 对象（只解析，不改写）。
+ * @param buffer - 日志内容。
+ * @param compressed - `true`（默认）表示 zstd 帧日志，`false` 表示未压缩的行式日志。
+ * @returns header 对象；不是合法会话日志时 `undefined`。
+ */
+export declare function readHeaderFromBuffer(buffer: Buffer, compressed?: boolean): SessionHeader | undefined;
+/**
+ * 把一个会话目录里的会话头读出来（**宽松**读法：扫目录找日志文件，取解压后的第一行）。
+ *
+ * 与 {@link readHeaderFromBuffer} 的区别是它不校验帧结构、也不要求 `type === 'session'`：
+ * 目录里可能有半截写入或手工改名的日志，扫描/删除路径宁可拿到一个「像头部」的对象，
+ * 也不要因为格式不严格就把整条会话当成不可读。
+ *
+ * 解压失败（截断、缺 zstd 支持）返回 `undefined`，调用方按「未知」处理。
+ * @param dir - 会话目录。
+ * @param cache - 以 `路径:mtime:size` 为键的头部缓存（可选；不传就现建一个）。
+ * @returns 头部对象，或 undefined。
+ */
+export declare function readSessionHeader(dir: string, cache?: Map<string, SessionHeader | undefined>): SessionHeader | undefined;
+/** {@link rewriteHeaderCwd} 成功时的结果。 */
+export interface HeaderRewriteSuccess {
+    buffer: Buffer;
+    rewritten: true;
+    header: SessionHeader;
+    frames?: number;
+    reason?: undefined;
+}
+/** {@link rewriteHeaderCwd} 无法改写时的结果（原样返回 buffer）。 */
+export interface HeaderRewriteFailure {
+    buffer: Buffer;
+    rewritten: false;
+    header?: SessionHeader;
+    frames?: number;
+    reason?: string;
+}
+/** {@link rewriteHeaderCwd} 的结果。 */
+export type HeaderRewriteResult = HeaderRewriteSuccess | HeaderRewriteFailure;
+/**
+ * 把会话头的 `cwd` 改写成另一条绝对路径。
+ *
+ * 只动 `cwd` 一个键，其余键（含该 generation 自己的字段）按原顺序逐字保留；
+ * 帧 0 之后的字节**原样接上**，所以事件批次一个字节都没变。
+ *
+ * @param buffer - 日志内容。
+ * @param newCwd - 改写后的绝对路径。
+ * @param options - `{compressed}`：帧日志（默认 `true`）或未压缩行式日志。
+ * @returns `{buffer, rewritten, header, frames?, reason?}`；无需改写或无法改写时
+ *   `rewritten: false` 并原样返回。
+ */
+export declare function rewriteHeaderCwd(buffer: Buffer, newCwd: string, options?: {
+    compressed?: boolean;
+}): HeaderRewriteResult;

package/lib/types/store/host.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 宿主侧的公共底座：`$DSH_HOME`、尽力而为的文件日志、以及 volatile 配置的解包。
+ *
+ * 这几段代码在两个插件里逐字重复——它们都是「DSH 宿主约定」而不是插件策略：
+ *   - `dshHome()` 认 `DSH_HOME` 环境变量（测试靠它把整个沙箱指到临时目录）；
+ *   - 宿主 stdout 不落盘，排障只能靠 `$DSH_HOME/logs/<name>.log`；
+ *   - 标了 `.volatile()` 的配置字段，Loader 交给 `apply` 的是活引用（`{get()}`）
+ *     而不是值，值在写盘后原地更新，所以**解包必须做两次**（进 schema 之前一次、
+ *     schema 出来之后再一次，后者是因为 schemastery 对 volatile 字段输出的也是活引用）。
+ *
+ * 文件日志的**行格式两边不同**（admin 是 `[时间] 级别 正文`，move 是 `时间 [级别] 正文`），
+ * 这是对外可见的排障产物，所以这里不做统一，而是把两种格式都作为预设导出，
+ * 由调用方显式选择（见 {@link LOG_LINE_LEVEL_FIRST} / {@link LOG_LINE_TIME_FIRST}）。
+ *
+ * @module dsh-session-ops/store/host
+ */
+/** 一行文件日志的 `{iso, level, message}`。 */
+export interface LogEntry {
+    iso: string;
+    level: string;
+    message: string;
+}
+/** 宿主 cordis 上下文里本模块用到的那一小块（只在 `createFileLogger` 里取 `logger`）。 */
+export interface LoggerContext {
+    logger?: Record<string, ((message: string) => unknown) | undefined> | undefined;
+}
+/** 日志行格式：`(entry) => 一整行（含结尾换行）`。 */
+export type LogLineFormatter = (entry: LogEntry) => string;
+/** 插件里到处用的日志函数。 */
+export type LogFn = (level: string, message: string) => void;
+/** `$DSH_HOME`：环境变量优先，默认 `~/.dsh`。 */
+export declare function dshHome(): string;
+/**
+ * 文件日志行格式之一：`[ISO 时间] 级别 正文`（`dsh-session-admin` 在用）。
+ * @param entry - `{iso, level, message}`。
+ * @returns 一整行（含结尾换行）。
+ */
+export declare const LOG_LINE_LEVEL_FIRST: LogLineFormatter;
+/**
+ * 文件日志行格式之一：`ISO 时间 [级别] 正文`（`dsh-session-move` 在用）。
+ * @param entry - `{iso, level, message}`。
+ * @returns 一整行（含结尾换行）。
+ */
+export declare const LOG_LINE_TIME_FIRST: LogLineFormatter;
+/** {@link createFileLogger} 的选项。 */
+export interface CreateFileLoggerOptions {
+    /** 日志文件名（不含 `.log`；默认 `dsh-session-ops`）。 */
+    name?: string;
+    /** 行格式（默认 {@link LOG_LINE_LEVEL_FIRST}）。 */
+    formatLine?: LogLineFormatter;
+}
+/**
+ * 尽力而为的文件日志：写 `$DSH_HOME/logs/<name>.log`，并顺带喂宿主 logger。
+ *
+ * 任何一步失败都静默吞掉——日志本身永远不该成为故障源（建目录失败、磁盘满了、
+ * 宿主 logger 不可用，都不影响插件机制）。
+ * @param ctx - Host cordis 上下文（只用 `ctx?.logger`，可为 undefined）。
+ * @param options - `{name, formatLine}`：日志文件名（不含 `.log`；默认
+ *   `dsh-session-ops`）与行格式（默认 {@link LOG_LINE_LEVEL_FIRST}）。
+ * @returns `(level, message) => void`，即插件里的 `log`。
+ */
+export declare function createFileLogger(ctx: LoggerContext | undefined, options?: CreateFileLoggerOptions): LogFn;
+/** 解包后的普通配置对象。 */
+export type PlainConfig = Record<string, unknown>;
+/**
+ * 解包 entry 配置里的 `.volatile()` 活引用。
+ * @param raw - entry 配置或普通配置对象。
+ * @returns 值已解包的浅拷贝。
+ */
+export declare function plainConfig(raw?: unknown): PlainConfig;
+/**
+ * 「可调用、收普通对象、返回普通对象」的 schema 形状（schemastery 的 `Config` 就是这种）。
+ *
+ * 本包不依赖 `@deepseek-ai/schemastery` 的运行时类型，只要求这个最小形状。
+ */
+export type ConfigSchemaLike = (raw?: any) => unknown;
+/**
+ * 解析一份 entry 配置：先解包输入的活引用，再交给 schema 校验并补默认值，最后**再解包
+ * 一次**——schemastery 对 `.volatile()` 字段输出的也是活引用，不收敛的话读到的就是
+ * `{ get() }` 对象（HTTP 面上会变成一个空对象）。
+ *
+ * schema 由调用方传入（本包只把 `@deepseek-ai/schemastery` 当类型来源），传进来的只要是
+ * 「可调用、收普通对象、返回带默认值的普通对象」即可。
+ * @param schema - 插件自己的 `Config`（schemastery 对象，可调用）。
+ * @param raw - entry 配置或普通配置对象。
+ * @returns 普通值配置。
+ */
+export declare function resolveVolatileConfig(schema: ConfigSchemaLike, raw?: unknown): PlainConfig;

package/lib/types/store/http.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 两个会话插件共用的 **HTTP 面**：JSON 响应封装、请求体读取、以及前缀路由的骨架。
+ *
+ * 路由协议（响应码与响应体）是两个插件对浏览器半边的**公开契约**，必须逐字一致，
+ * 所以它只在写一份：
+ *   - 403 `{ok:false,error:{code:'forbidden',message:'forbidden'}}` —— 信任栅栏拒绝；
+ *   - 404 `{ok:false,error:{code:'not-found',message:'unknown method'}}` —— 路径没落在
+ *     前缀下，或方法名里还有 `/`；
+ *   - 404 `{ok:false,error:{code:'not-found',message:'unknown method <m>'}}` —— 方法不在表里；
+ *   - 200 `{ok:true,value}`；
+ *   - 400 `{ok:false,error:{code:'bad-request',message:<err.message>}}` —— 处理器抛错。
+ *   `GET` 的载荷是 query string，其余方法读 `JSON` 请求体（1 MiB 上限）。
+ *
+ * **信任栅栏本身刻意不在这里**：两个插件的判定依据不同（`dsh-session-admin` 看
+ * `Host` 头 + `sec-fetch-site`/`Origin` + `allowHosts` 的 host/hostname 匹配；
+ * `dsh-session-move` 看 socket 的 `remoteAddress` + `allowHosts` 精确字符串匹配），
+ * 语义不同就不能合并——合并必然改动其中一边的对外行为。这里只收一个
+ * `trustRequest(req) => boolean` 回调。
+ *
+ * 同理，`writeJson` 的 `content-length` 与 `readJsonBody` 的严格程度两边也不同，
+ * 都用显式开关保留原状（见各参数）。
+ *
+ * @module dsh-session-ops/store/http
+ */
+/**
+ * 本模块用到的请求形状（Node 的 `IncomingMessage` 与测试里的假请求都满足它）。
+ *
+ * 刻意写成最小本地接口而不是直接引用 `node:http`：两个插件只用到这几个字段，
+ * 测试里的假请求也不实现完整的 `IncomingMessage`。
+ */
+export interface HttpRequest extends AsyncIterable<Buffer> {
+    url?: string | undefined;
+    method?: string | undefined;
+    headers?: Record<string, string | string[] | undefined> | undefined;
+    socket?: {
+        remoteAddress?: string | undefined;
+    } | undefined;
+}
+/** 本模块用到的响应形状（Node 的 `ServerResponse` 与测试里的假响应都满足它）。 */
+export interface HttpResponse {
+    writeHead(status: number, headers: Record<string, string | number>): unknown;
+    end(body?: string): unknown;
+}
+/** 路由方法表里的一个处理器：收载荷，返回值包成 `{ok:true,value}`。 */
+export type ApiMethod = (payload: any) => unknown | Promise<unknown>;
+/** {@link createApiHandler} 的选项。 */
+export interface CreateApiHandlerOptions {
+    /** 路由前缀，如 `/session-admin/api`。 */
+    prefix: string;
+    /** 方法名 → `async (payload) => value`。 */
+    methods: Record<string, ApiMethod | undefined>;
+    /** `(req) => boolean`：请求是否来自受信的浏览器（各插件自己的栅栏）。 */
+    trustRequest?: ((req: HttpRequest) => boolean) | undefined;
+    /** `(level, message) => void`（可为 undefined）。 */
+    log?: ((level: string, message: string) => void) | undefined;
+    /** 读请求体，默认 {@link readJsonBody}（宽松）。 */
+    readBody?: (req: HttpRequest) => Promise<unknown>;
+    /** 透传给 {@link writeJson}。 */
+    contentLength?: boolean;
+}
+/**
+ * 写一个 JSON 响应。
+ * @param res - Node HTTP 响应。
+ * @param status - 状态码。
+ * @param body - 任意可 JSON 序列化的值。
+ * @param options - `{contentLength}`：是否带上 `content-length` 头。默认 `false`
+ *   （`dsh-session-move` 的原样行为，响应走 chunked）；`dsh-session-admin` 传 `true`
+ *   以保留它原有的 `content-length`。
+ * @returns 无。
+ */
+export declare function writeJson(res: HttpResponse, status: number, body: unknown, options?: {
+    contentLength?: boolean;
+}): void;
+/**
+ * 读一个 JSON 请求体（上限 1 MiB）。
+ *
+ * 严格程度由调用方选，因为两个插件原本就不一样：
+ *   - `requireObject: false`（默认，`dsh-session-admin` 的行为）：不 trim、不校验类型，
+ *     空 body 返回 `{}`，其余原样交给 `JSON.parse`（一个空白 body 会抛出
+ *     `Unexpected end of JSON input`，进而变成 400）；
+ *   - `requireObject: true`（`dsh-session-move` 的行为）：trim 后空串返回 `{}`，
+ *     解析结果必须是**普通对象**，否则抛 `request body must be a JSON object`。
+ * @param req - Node HTTP 请求。
+ * @param options - `{requireObject}`。
+ * @returns 解析出来的载荷对象。
+ */
+export declare function readJsonBody(req: HttpRequest, options?: {
+    requireObject?: boolean;
+}): Promise<unknown>;
+/**
+ * 造一个 `kind: 'prefix'` 路由处理器（`ctx.webServer.register({kind:'prefix', path, handler})` 的 `handler`）。
+ *
+ * 方法表里的每个处理器收到 `payload`，返回值包成 `{ok:true,value}`；抛错变成 400 并写一行
+ * `<method> failed: <message>` 日志。`GET` 的载荷是 query string（全部是字符串）。
+ * @param options - 见下。
+ * @param options.prefix - 路由前缀，如 `/session-admin/api`。
+ * @param options.methods - 方法名 → `async (payload) => value`。
+ * @param options.trustRequest - `(req) => boolean`：请求是否来自受信的浏览器（各插件自己的栅栏）。
+ * @param options.log - `(level, message) => void`（可为 undefined）。
+ * @param options.readBody - 读请求体，默认 {@link readJsonBody}（宽松）；`dsh-session-move`
+ *   传 `(req) => readJsonBody(req, {requireObject: true})`。
+ * @param options.contentLength - 透传给 {@link writeJson}。
+ * @returns `async (req, res) => void`。
+ */
+export declare function createApiHandler(options: CreateApiHandlerOptions): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/lib/types/store/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `dsh-session-ops/lib/store` —— 本包内部的**会话存储原语**。
+ *
+ * 这一层只做库：没有模型工具、没有槽位注册、没有 DSH 插件生命周期代码，
+ * 也**零 `@deepseek-ai/*` 运行时依赖**（只用 node 内置模块）。删除半边与搬迁半边
+ * 共用它，避免两边逐字重复同一套会话存储知识。
+ *
+ * 五个子模块：
+ *   - {@link module:dsh-session-ops/store/paths}：项目目录键 `--C-proj--` 的编解码、
+ *     会话目录与 generation 文件名的命名规则；
+ *   - {@link module:dsh-session-ops/store/frames}：`session[.vN].jsonl[.zstd]` 的帧扫描、
+ *     头部读取（两种严格度）与 cwd 改写；
+ *   - {@link module:dsh-session-ops/store/registry}：工作区注册表成员表 / 归档集合、
+ *     驻留会话、「正在跑一轮」判定、内存里三处 cwd 的重定向；
+ *   - {@link module:dsh-session-ops/store/host}：`$DSH_HOME`、尽力而为的文件日志、
+ *     volatile 配置解包；
+ *   - {@link module:dsh-session-ops/store/http}：两个半边共用的 HTTP 面（JSON 响应封装、
+ *     请求体读取、前缀路由骨架；**信任栅栏按插件语义不同，不在这里**）。
+ *
+ * 有意**没有**放进来的东西（语义不同或只有一边有）：两套信任栅栏、迁移的三步改名策略
+ * （`planMove`/`applyPlan`）、磁盘扫描与范围筛选（删除半边专有）、项目记忆跟随
+ * （搬迁半边专有）、模型工具与槽位定义。
+ *
+ * @module dsh-session-ops/store
+ */
+export * from './paths.js';
+export * from './frames.js';
+export * from './registry.js';
+export * from './host.js';
+export * from './http.js';