mu-agent-bridge 1.0.34 → 1.0.39

package/dist/src-ts/plugins/dsh/session-history.js

@@ -0,0 +1,371 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DshSessionHistoryProvider = void 0;
+exports.decodeDshZstdFrames = decodeDshZstdFrames;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_zlib_1 = require("node:zlib");
+const MAX_COMPRESSED_BYTES = 32 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 128 * 1024 * 1024;
+const MAX_SESSIONS = 10_000;
+const MAX_TURNS = 100_000;
+const KNOWN_EVENTS = new Set([
+    "agent-preset/selected", "agent/inbox/spliced", "approval/asked", "approval/decided", "approval/policy", "assistant/attempt", "assistant/message",
+    "command/done", "command/run", "compaction/end", "compaction/prune", "compaction/start", "compaction/summary", "deliverables/presented",
+    "developer/message", "feedback/message-delete", "feedback/message-put", "feedback/record", "goal/change", "hook/invoked", "hook/result",
+    "image/offload", "llm/retry", "llm/retry-started", "model/selection", "permission/preset", "plan/mode", "request/context", "request/header",
+    "sandbox/mode", "schedule/change", "session-log-deepseek/delivery-accepted", "session/end-seed", "session/title", "session/title-llm-request",
+    "step/end", "step/start", "subagent/catalog", "subagent/descriptor", "subagent/model-selection-policy", "system/message", "team/member",
+    "team/message/delivered", "team/message/queued", "team/task", "todo/write", "tool-workflow/agent-end", "tool-workflow/agent-start",
+    "tool-workflow/run-end", "tool-workflow/run-start", "tool/call", "tool/ptc-dispatch", "tool/ptc-dispatch-start", "tool/result", "turn/end",
+    "turn/start", "user/message", "web/deepseek-search-llm-request", "workspace/changes",
+]);
+const unsupported = (reason) => ({ supported: false, reason });
+const validTime = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && Number.isFinite(new Date(value).getTime());
+/** DSH 将头部与每批事件编码为独立 zstd 帧；Node 的解压器只消费首帧，必须逐帧处理。 */
+function decodeDshZstdFrames(bytes) {
+    const decoded = [];
+    let offset = 0, total = 0;
+    const requireBytes = (position, length) => { if (position + length > bytes.length)
+        throw new Error("DSH zstd 帧被截断"); };
+    while (offset < bytes.length) {
+        if (decoded.length > MAX_TURNS)
+            throw new Error("DSH zstd 帧数量超过读取上限");
+        const start = offset;
+        requireBytes(offset, 5);
+        if (bytes.readUInt32LE(offset) !== 0xfd2fb528)
+            throw new Error("DSH zstd 帧魔数无效");
+        const descriptor = bytes[offset + 4];
+        if (descriptor & 0x18)
+            throw new Error("DSH zstd 帧含保留标记");
+        const single = Boolean(descriptor & 0x20), sizeFlag = descriptor >>> 6, checksum = Boolean(descriptor & 4);
+        offset += 5 + (single ? 0 : 1) + [0, 1, 2, 4][descriptor & 3] + (sizeFlag ? [0, 2, 4, 8][sizeFlag] : single ? 1 : 0);
+        requireBytes(offset, 0);
+        let last = false;
+        while (!last) {
+            requireBytes(offset, 3);
+            const block = bytes.readUIntLE(offset, 3);
+            last = Boolean(block & 1);
+            const kind = (block >>> 1) & 3, size = block >>> 3;
+            if (kind === 3)
+                throw new Error("DSH zstd 块类型无效");
+            offset += 3 + (kind === 1 ? 1 : size);
+            requireBytes(offset, 0);
+        }
+        offset += checksum ? 4 : 0;
+        requireBytes(offset, 0);
+        const frame = (0, node_zlib_1.zstdDecompressSync)(bytes.subarray(start, offset), { maxOutputLength: MAX_EXPANDED_BYTES - total });
+        total += frame.length;
+        if (total > MAX_EXPANDED_BYTES)
+            throw new Error("DSH 解压日志超过读取上限");
+        decoded.push(frame);
+    }
+    return Buffer.concat(decoded, total);
+}
+class DshSessionHistoryProvider {
+    options;
+    scope;
+    limitation = "读取的是 DSH 官方 v4 持久化会话日志；实时尚未落盘的事件、未知格式与损坏日志会标为不完整。";
+    mode = "all";
+    root;
+    constructor(options = {}) {
+        this.options = options;
+        this.root = (0, node_path_1.resolve)(options.sessionsRoot ?? (0, node_path_1.join)(process.env.DSH_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), ".dsh"), "sessions"));
+        this.scope = `dsh:persisted:${(0, node_crypto_1.createHash)("sha256").update(this.root).digest("hex").slice(0, 24)}`;
+    }
+    async listSessions(query) {
+        if (this.options.unavailableReason?.())
+            return unsupported(this.options.unavailableReason());
+        const invalid = this.validate(query, 100);
+        if (invalid)
+            return unsupported(invalid);
+        const root = await this.realRoot();
+        if (typeof root !== "string")
+            return root;
+        const discovered = await this.discover(root);
+        const fingerprint = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(discovered.entries.map(item => [item.id, item.generation, item.mtime]))).digest("hex");
+        const offset = this.cursor(query.cursor, fingerprint, discovered.entries.length, "dsh-list");
+        if (offset instanceof Error)
+            throw offset;
+        const sessions = discovered.entries.slice(offset, offset + Math.min(query.limit, 100)).map(item => ({ id: item.id, title: item.id, updatedAt: new Date(item.mtime).toISOString() }));
+        return {
+            supported: true,
+            sessions,
+            ...(offset + sessions.length < discovered.entries.length ? { nextCursor: `dsh-list:${fingerprint}:${offset + sessions.length}` } : {}),
+            complete: discovered.reasons.length === 0,
+            missingReasons: discovered.reasons,
+            readAt: new Date().toISOString(),
+        };
+    }
+    async readSession(query) {
+        if (this.options.unavailableReason?.())
+            return unsupported(this.options.unavailableReason());
+        const invalid = this.validate(query, 1000);
+        if (invalid)
+            return unsupported(invalid);
+        const since = this.parseSince(query.since);
+        if (since instanceof Error)
+            return unsupported(since.message);
+        const root = await this.realRoot();
+        if (typeof root !== "string")
+            return root;
+        const discovered = await this.discover(root);
+        const entry = discovered.entries.find(item => item.id === query.sessionId);
+        if (!entry)
+            return unsupported("DSH 会话不在当前可验证的持久化日志列表中");
+        const parsed = await this.readEntry(root, entry);
+        // 先完整解析并校验日志，再按时间筛选，避免过滤掩盖损坏或未知事件。
+        const filteredTurns = since === undefined ? parsed.turns : parsed.turns.filter(turn => turn.time !== undefined && Date.parse(turn.time) >= Date.parse(since));
+        const fingerprint = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(["dsh-read", entry.id, entry.generation, entry.mtime, since ?? null, filteredTurns])).digest("hex");
+        const offset = this.cursor(query.cursor, fingerprint, filteredTurns.length, "dsh-read");
+        if (offset instanceof Error)
+            throw offset;
+        const turns = filteredTurns.slice(offset, offset + Math.min(query.limit, 1000));
+        return {
+            supported: true,
+            session: parsed.session,
+            turns,
+            ...(offset + turns.length < filteredTurns.length ? { nextCursor: `dsh-read:${fingerprint}:${offset + turns.length}` } : {}),
+            complete: parsed.complete,
+            missingReasons: parsed.reasons,
+            readAt: new Date().toISOString(),
+        };
+    }
+    async realRoot() {
+        try {
+            const resolved = await (0, promises_1.realpath)(this.root);
+            const info = await (0, promises_1.lstat)(this.root);
+            if (!info.isDirectory() || info.isSymbolicLink() || resolved !== this.root)
+                return unsupported("DSH 会话目录不是受信任的真实目录");
+            return resolved;
+        }
+        catch {
+            return unsupported("DSH 持久化会话目录不存在或不可读");
+        }
+    }
+    async discover(root) {
+        const entries = [];
+        const reasons = [];
+        let projects;
+        try {
+            projects = await (0, promises_1.readdir)(root, { withFileTypes: true });
+        }
+        catch {
+            return { entries, reasons: ["无法完整枚举 DSH 项目会话目录"] };
+        }
+        for (const project of projects) {
+            if (!project.isDirectory()) {
+                if (project.isSymbolicLink())
+                    reasons.push("会话目录包含符号链接，已略过");
+                continue;
+            }
+            const projectPath = (0, node_path_1.join)(root, project.name);
+            if (!await this.inside(root, projectPath)) {
+                reasons.push("项目会话目录路径越界，已略过");
+                continue;
+            }
+            let directories;
+            try {
+                directories = await (0, promises_1.readdir)(projectPath, { withFileTypes: true });
+            }
+            catch {
+                reasons.push("部分项目会话目录不可读");
+                continue;
+            }
+            for (const directory of directories) {
+                if (!directory.isDirectory()) {
+                    if (directory.isSymbolicLink())
+                        reasons.push("会话目录包含符号链接，已略过");
+                    continue;
+                }
+                const dir = (0, node_path_1.join)(projectPath, directory.name);
+                if (!await this.inside(root, dir)) {
+                    reasons.push("会话文件目录路径越界，已略过");
+                    continue;
+                }
+                let files;
+                try {
+                    files = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+                }
+                catch {
+                    reasons.push("部分会话文件目录不可读");
+                    continue;
+                }
+                const candidates = files.flatMap(file => {
+                    const match = file.name.match(/^session(?:\.v(\d+))?\.jsonl(\.zstd)?$/);
+                    return match ? [{ file, generation: match[1] ? Number(match[1]) : 0, compressed: Boolean(match[2]) }] : [];
+                }).sort((a, b) => b.generation - a.generation);
+                const canonical = candidates[0];
+                if (!canonical) {
+                    if (files.some(file => file.name.startsWith("session.")))
+                        reasons.push("会话目录使用无法识别的日志格式");
+                    continue;
+                }
+                if (canonical.generation !== 4) {
+                    reasons.push(`会话 ${directory.name} 使用不支持的 v${canonical.generation} 持久化代际`);
+                    continue;
+                }
+                if (candidates.length > 1)
+                    reasons.push(`会话 ${directory.name} 存在多个日志代际，无法确认规范版本`);
+                if (canonical.file.isSymbolicLink() || !canonical.file.isFile()) {
+                    reasons.push(`会话 ${directory.name} 的日志不是普通文件`);
+                    continue;
+                }
+                const path = (0, node_path_1.join)(dir, canonical.file.name);
+                if (!await this.inside(root, path)) {
+                    reasons.push(`会话 ${directory.name} 的日志路径越界`);
+                    continue;
+                }
+                try {
+                    const stat = await (0, promises_1.lstat)(path);
+                    if (stat.size > MAX_COMPRESSED_BYTES) {
+                        reasons.push(`会话 ${directory.name} 超过压缩日志大小上限`);
+                        continue;
+                    }
+                    entries.push({ path, id: directory.name, mtime: stat.mtimeMs, generation: canonical.generation, compressed: canonical.compressed });
+                }
+                catch {
+                    reasons.push(`会话 ${directory.name} 日志无法读取`);
+                }
+            }
+        }
+        entries.sort((a, b) => b.mtime - a.mtime || a.id.localeCompare(b.id));
+        if (entries.length > MAX_SESSIONS) {
+            entries.length = MAX_SESSIONS;
+            reasons.push(`会话数超过 ${MAX_SESSIONS} 条上限`);
+        }
+        return { entries, reasons: [...new Set(reasons)] };
+    }
+    async inside(root, path) {
+        try {
+            const real = await (0, promises_1.realpath)(path);
+            const rel = (0, node_path_1.relative)(root, real);
+            return rel !== ".." && !rel.startsWith(`..${node_path_1.sep}`) && !(0, node_path_1.isAbsolute)(rel);
+        }
+        catch {
+            return false;
+        }
+    }
+    async readEntry(root, entry) {
+        const reasons = [];
+        const fail = (reason) => ({ session: { id: entry.id, title: entry.id }, turns: [], complete: false, reasons: [...new Set([...reasons, reason])] });
+        try {
+            if (!await this.inside(root, entry.path))
+                return fail("DSH 会话日志路径越界或为符号链接");
+            const before = await (0, promises_1.lstat)(entry.path);
+            if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_COMPRESSED_BYTES)
+                return fail("DSH 会话日志不是普通文件或超过读取上限");
+            const handle = await (0, promises_1.open)(entry.path, node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW ?? 0));
+            let bytes;
+            try {
+                const opened = await handle.stat();
+                if (!opened.isFile() || opened.size > MAX_COMPRESSED_BYTES || opened.ino !== before.ino)
+                    return fail("DSH 会话日志在打开期间发生变化");
+                bytes = await handle.readFile();
+                const after = await handle.stat();
+                if (opened.ino !== after.ino || opened.size !== after.size || opened.mtimeMs !== after.mtimeMs || bytes.byteLength !== after.size)
+                    return fail("DSH 会话日志在读取期间发生变化");
+            }
+            finally {
+                await handle.close();
+            }
+            const data = entry.compressed ? decodeDshZstdFrames(bytes) : bytes;
+            if (data.byteLength > MAX_EXPANDED_BYTES)
+                return fail("DSH 解压日志超过读取上限");
+            const text = data.toString("utf8");
+            if (!text.endsWith("\n"))
+                return fail("DSH 会话日志最后一条记录不完整");
+            const rows = text.slice(0, -1).split("\n");
+            if (!rows.length || rows.length > MAX_TURNS + 1)
+                return fail("DSH 会话记录数量超过读取上限");
+            const header = JSON.parse(rows[0]);
+            if (header.type !== "session" || header.version !== 4 || header.id !== entry.id || !validTime(header.createdAt) || typeof header.isSeeded !== "boolean" || !Number.isSafeInteger(header.delegationDepth) || header.delegationDepth < 0)
+                return fail("DSH 会话头格式或身份无法验证");
+            const turns = [];
+            let complete = true;
+            for (let index = 1; index < rows.length; index++) {
+                let event;
+                try {
+                    event = JSON.parse(rows[index]);
+                }
+                catch {
+                    return fail("DSH 会话日志包含损坏记录");
+                }
+                if (!event || event.seq !== index - 1 || typeof event.type !== "string" || !validTime(event.time) || typeof event.data !== "object" || event.data === null)
+                    return fail("DSH 会话事件序号、时间或结构无法验证");
+                if (!KNOWN_EVENTS.has(event.type) && event.ignorable !== true) {
+                    complete = false;
+                    reasons.push(`存在未知且不可安全忽略的 DSH 事件：${event.type}`);
+                    continue;
+                }
+                if (event.type !== "user/message" && event.type !== "assistant/message")
+                    continue;
+                const declaredRole = event.type === "user/message" ? event.data.role : event.data.message?.role;
+                if (declaredRole !== undefined && declaredRole !== (event.type === "user/message" ? "user" : "assistant")) {
+                    complete = false;
+                    reasons.push("DSH 消息事件与角色声明冲突，已排除");
+                    continue;
+                }
+                const content = event.type === "user/message" ? event.data.content : event.data.message?.content;
+                if (!Array.isArray(content)) {
+                    complete = false;
+                    reasons.push("部分 DSH 消息缺少可验证正文");
+                    continue;
+                }
+                const parts = [];
+                for (const block of content) {
+                    if (!block || typeof block !== "object" || typeof block.type !== "string") {
+                        complete = false;
+                        reasons.push("部分 DSH 消息包含无法解释的正文块");
+                        continue;
+                    }
+                    if (block.type === "reasoning" || block.type === "tool-call")
+                        continue;
+                    if (block.type === "text" && typeof block.text === "string")
+                        parts.push(block.text);
+                    else {
+                        complete = false;
+                        reasons.push(`DSH ${block.type} 正文块未纳入文本历史读取`);
+                    }
+                }
+                const message = parts.join("\n").trim();
+                if (message)
+                    turns.push({ id: `${entry.id}:${event.seq}`, role: event.type === "user/message" ? "user" : "assistant", text: message, time: new Date(event.time).toISOString() });
+            }
+            return { session: { id: entry.id, title: entry.id, updatedAt: new Date(before.mtimeMs).toISOString() }, turns, complete, reasons: [...new Set(reasons)] };
+        }
+        catch (error) {
+            return fail(error instanceof Error && /maximum output length|larger than/.test(error.message) ? "DSH 解压日志超过读取上限" : "DSH 会话日志无法按官方 v4 格式完整解析");
+        }
+    }
+    cursor(cursor, fingerprint, total, prefix) {
+        if (cursor === undefined)
+            return 0;
+        const match = cursor.match(/^(dsh-list|dsh-read):([a-f0-9]{64}):(\d+)$/);
+        if (!match || match[1] !== prefix || match[2] !== fingerprint)
+            return new Error("DSH 历史游标无效或内容已变化");
+        const offset = Number(match[3]);
+        return Number.isSafeInteger(offset) && offset >= 0 && offset < total ? offset : new Error("DSH 历史游标位置无效");
+    }
+    validate(query, max) {
+        if (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > max)
+            return `DSH 每页数量必须为 1–${max}`;
+        if (query.cursor !== undefined && (typeof query.cursor !== "string" || !query.cursor.trim()))
+            return "DSH 历史游标无效";
+        return undefined;
+    }
+    parseSince(value) {
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.test(value))
+            return new Error("DSH since 必须是 ISO 8601 时间");
+        const timestamp = Date.parse(value);
+        if (!Number.isFinite(timestamp))
+            return new Error("DSH since 必须是有效的 ISO 8601 时间");
+        return new Date(timestamp).toISOString();
+    }
+}
+exports.DshSessionHistoryProvider = DshSessionHistoryProvider;