dsh-plugin-om 0.0.0

package/dist/index.mjs

@@ -0,0 +1,782 @@
+import { z } from "zod";
+//#region src/constants.ts
+/**
+* 共享常量：集中定义插件级魔法字符串与事件名，避免散落各模块。
+*/
+/** 插件标识：压缩消息 source.plugin 取值与日志前缀。 */
+const PLUGIN_LABEL = "dsh-plugin-om";
+/** 压缩日志标签名：<om-history>...</om-history> 包裹观察/反思日志块。 */
+const HISTORY_TAG = "om-history";
+/** 影子价格认领事件类型：token-meter 据此识别被替换（遮蔽）的表层节点。 */
+const CLAIM_EVENT = "compaction/prune";
+//#endregion
+//#region src/log-index.ts
+/**
+* 查找 seq 在表层节点序列中的下标（不在则返回 -1）。
+* 表层节点按日志顺序排列，用于压缩边界定位与遮蔽范围计算。
+*/
+function surfaceIndexOf(nodes, seq) {
+	for (let i = 0; i < nodes.length; i += 1) if (nodes[i] === seq) return i;
+	return -1;
+}
+/** 提取一条消息事件的 message_id（user/assistant/tool-result 消息均有稳定 id；其余事件无）。 */
+function messageIdOfEvent(event) {
+	if (!event) return void 0;
+	if (event.type === "user/message") return String(event.data.id ?? "");
+	if (event.type === "assistant/message") return String(event.data.message.id ?? "");
+	if (event.type === "tool/result") return String(event.data.message.id ?? "");
+}
+/** 消息索引：按日志顺序列出全部消息事件，并按 message_id 定位其在消息序列中的下标。 */
+function indexMessages(session) {
+	/** 按日志顺序的消息事件列表。 */
+	const messages = [];
+	/** message_id → 序列下标映射。 */
+	const byId = /* @__PURE__ */ new Map();
+	/** 会话全部事件。 */
+	const events = session.events;
+	for (let seq = 0; seq < events.length; seq += 1) {
+		/** 当前待检查事件。 */
+		const event = events[seq];
+		if (!event) continue;
+		if (event.type !== "user/message" && event.type !== "assistant/message" && event.type !== "tool/result") continue;
+		/** 消息 id（缺失则跳过该事件）。 */
+		const id = messageIdOfEvent(event);
+		if (!id) continue;
+		/** 本条消息在消息序列中的下标。 */
+		const index = messages.length;
+		messages.push({
+			seq,
+			id,
+			type: event.type
+		});
+		byId.set(id, index);
+	}
+	return {
+		messages,
+		byId
+	};
+}
+//#endregion
+//#region src/utils.ts
+/** 判断值是否为普通对象：typeof object 且非 null 且非数组（类型收窄用）。 */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 抛出带插件前缀的错误（never 返回：调用后控制流终止）。 */
+function fail(message) {
+	throw new Error(`dsh-plugin-om: ${message}`);
+}
+/**
+* 校验配置数值：必须是有限数且在 [min, max] 内（可选整数约束），
+* 不满足时抛出带插件前缀的错误。
+*/
+function assertNumber(name, value, { min = 0, max = Infinity, integer = false } = {}) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) fail(`config ${name} must be a finite number in [${min}, ${max}]`);
+	if (integer && !Number.isInteger(value)) fail(`config ${name} must be an integer`);
+}
+/** 生成 uuid：优先 crypto.randomUUID，回退为时间戳+随机串拼接（保证唯一性）。 */
+function uuid() {
+	/** 全局 crypto 对象（提供 randomUUID 的现代环境才存在）。 */
+	const cryptoObj = globalThis.crypto;
+	if (cryptoObj && typeof cryptoObj.randomUUID === "function") return cryptoObj.randomUUID();
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+/** 提取 content 数组中的纯文本块（type === 'text' 的 block.text 拼接）。 */
+function blocksToText(blocks) {
+	if (!Array.isArray(blocks)) return "";
+	/** 拼接结果缓冲区。 */
+	const out = [];
+	for (const block of blocks) if (isRecord(block) && block.type === "text" && typeof block.text === "string") out.push(block.text);
+	return out.join("");
+}
+/** 面向 recall 的完整消息呈现：text 原样；tool-call 展开（参数=代码）；tool-result 取文本。 */
+function renderMessageText(message) {
+	if (!message || !Array.isArray(message.content)) return "";
+	/** 各内容块呈现后的拼接缓冲区。 */
+	const parts = [];
+	for (const block of message.content) if (block.type === "text") parts.push(block.text);
+	else if (block.type === "tool-call") parts.push(`[tool-call ${block.name} id=${String(block.id)}]
+${safeJson(block.arguments)}`);
+	else if (block.type === "tool-result") parts.push(blocksToText(block.content));
+	return parts.join("\n");
+}
+/** 安全 JSON 序列化：序列化失败时退回 String 呈现（避免渲染异常）。 */
+function safeJson(value) {
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+/** 主会话判定：subagent 会话 header.origin === 'subagent'（压缩/recall 仅主会话生效）。 */
+function isMainSession(session) {
+	return session.header?.origin !== "subagent";
+}
+/** 解析会话路由目标（provider/model），未路由时返回 undefined。 */
+function routedTarget(session) {
+	try {
+		/** 会话请求头中的路由配置。 */
+		const config = session.requestHeader()?.config;
+		if (config?.provider && config.model) return {
+			provider: config.provider,
+			model: config.model
+		};
+	} catch {}
+}
+//#endregion
+//#region src/summarize.ts
+/**
+* 摘要子会话（OM 观察/反思）：两级阈值下分别 fork 子会话——
+*  - observe：把「上下文中最后一次 <om-history> 之后」的未压缩消息压缩为观察日志
+*    （结果追加到旧摘要末尾，替换被压缩消息区间）；
+*  - reflect：把当前 <om-history> 精简合并（结果替换单个摘要节点）。
+*
+* 提示词不内嵌消息/摘要全文：fork 子会话继承父会话日志前缀（seed 截断于最后一个
+* turn/end，宿主 fork 提供方语义），按上下文中的 <om-history> 定位待处理部分；
+* message_id 对照表与中断标记由插件从日志计算后内嵌（id 非原文，保留关键 id 供
+* recall 检索）。摘要以工具调用为核心节点，不限于 run_code。
+* 仅主会话生效（index.ts 守卫）。
+*/
+/** 观察者 persona：只针对未压缩消息产出观察日志，不用工具、不展示思考。 */
+const OBSERVER_PERSONA = "你是 dsh-plugin-om 的上下文观察者（Observer，机制参考 Mastra Observational Memory）：把会话中尚未压缩的消息压缩为一份观察日志。不用工具、不展示思考、不评价代码、不输出多余文字。";
+/** 反思者 persona：只精简合并当前摘要，不用工具、不展示思考。 */
+const REFLECTOR_PERSONA = "你是 dsh-plugin-om 的上下文反思者（Reflector，机制参考 Mastra Observational Memory）：把当前 <om-history> 压缩日志精简合并为一份更紧凑的日志。不用工具、不展示思考、不输出多余文字。";
+/**
+* 构建观察提示词：规则（消息概括为要点 / 工具调用按目的聚合——不限于 run_code /
+* 仅关键消息保留 message_id / 中断标注 / 未完成写进度与下一步）+ message_id 对照表 +
+* 中断标记 + 追加说明。全文由继承上下文提供。
+*/
+function buildObservePrompt(options) {
+	/** 对照表段落（无则标注「无」）。 */
+	const tableSection = options.table.length > 0 ? options.table : ["（无）"];
+	/** 中断标记段落（无则标注「无」）。 */
+	const interruptionSection = options.interruptions.length > 0 ? options.interruptions : ["（无）"];
+	return [
+		`你继承的会话上下文中，最后一次 <${HISTORY_TAG}> 块之后的全部消息都是「未压缩消息」；只对这些消息做压缩，忽略更早的历史。`,
+		`如果上下文里还没有 <${HISTORY_TAG}> 块，则除本消息外的全部消息都是未压缩消息。`,
+		"",
+		"【规则】",
+		"- 用户消息概括为 user_message 条目（保留需求要点与关键事实：数字、路径、命令、决定），仅对关键消息保留 message_id（格式：user_message message_id:<id> text:<要点>）。关键消息指开启新任务/提出需求的请求、包含关键决策或不可再得事实的输入；普通消息（寒暄、重复、可推断内容）可以省略 message_id。",
+		"- 所有工具调用（run_code 与其他工具同等对待，不限于 run_code）按调用目的聚合为一行 toolcall message_id:<该组最后一条消息的 message_id> purpose:<聚合目的> summary:<行为与结果摘要>；工具组内部细节（参数、完整输出）不保留，需要原文时用 recall 按 message_id 回看。",
+		"- 若【中断标记】非空，在对应位置明确写出中断（例如「被用户打断，因此上一段工作未完成」），帮助后续理解用户为何再次输入消息、为何不延续之前的工作。",
+		"- 若当前工作看起来未完成（最后一次工具调用没有结果、或对话被中断/异常结束），在日志末尾说明当前进度与下一步要做什么。",
+		`- 只输出日志条目本身；不要 <${HISTORY_TAG}> 标签、不要解释、不要复述规则。`,
+		"",
+		"【message_id 对照表】（按顺序对应你上下文中的消息，用于产出正确的 message_id）",
+		...tableSection,
+		"",
+		"【中断标记】",
+		...interruptionSection,
+		"",
+		...options.hasOldHistory ? [`【说明】你的压缩结果会被直接追加到上一次压缩产物（<${HISTORY_TAG}>）的末尾，条目格式须与上一条目保持一致。`] : [`【说明】你的压缩结果将成为第一条 <${HISTORY_TAG}> 压缩日志。`]
+	].join("\n");
+}
+/** 构建反思提示词：精简合并当前 <om-history>；全文由继承上下文提供。 */
+function buildReflectPrompt() {
+	return [
+		`你继承的会话上下文中包含当前的 <${HISTORY_TAG}> 压缩日志（最后一次 <${HISTORY_TAG}> 块）。`,
+		"只对这份压缩日志做精简合并；不要涉及日志之外的消息。",
+		"",
+		"【规则】",
+		"- 用户消息保留要点，仅保留关键 message_id（格式：user_message message_id:<id> text:<要点>）；可省略的 message_id 删除。",
+		"- toolcall 条目按调用目的进一步聚合，保留组内最后一条消息的 message_id；不重要的条目 summary 写「（略）」。",
+		"- 保留中断说明与未完成说明（若原日志中有）。",
+		"- 过时事实丢弃，不逐字复制旧文本。",
+		`- 只输出合并后的日志条目本身；不要 <${HISTORY_TAG}> 标签、不要解释、不要复述规则。`,
+		"",
+		`【说明】你的合并结果会替换当前的 <${HISTORY_TAG}> 块内容。`
+	].join("\n");
+}
+/**
+* Fork 子会话执行一次摘要（观察或反思），返回文本；失败或无法 fork 返回 null。
+* 工具被 toolFilter 禁用，输出长度受 maxTokens 限制。
+*/
+async function runSummarySubagent(ctx, agent, persona, prompt, maxTokens, signal) {
+	/** subagents 服务（缺失则无法分叉摘要）。 */
+	const subagents = ctx.get("subagents");
+	if (!subagents) {
+		ctx.logger.warn("dsh-plugin-om: 未找到 subagents 服务，跳过摘要分叉");
+		return null;
+	}
+	if (!subagents.getProvider("fork")) {
+		ctx.logger.warn("dsh-plugin-om: fork 子代理提供方未注册，跳过摘要分叉");
+		return null;
+	}
+	/** 本次 fork 运行的句柄（用于取结果与 dispose）。 */
+	let run;
+	try {
+		run = await subagents.start("fork", {
+			label: "om-summary",
+			prompt: [{
+				type: "text",
+				text: prompt
+			}],
+			parent: agent,
+			persona,
+			toolFilter: { allow: [] },
+			agentOptions: { maxTokens },
+			...signal !== void 0 ? { signal } : {}
+		});
+		/** 子代理运行结果。 */
+		const result = await run.result;
+		/** 拼接、去标签、去首尾空白的摘要文本。 */
+		const text = blocksToText(Array.isArray(result.output) ? result.output : []).trim().replace(new RegExp(`</?${HISTORY_TAG}>`, "g"), "").trim();
+		if (result.stopReason !== "completed" || text.length === 0) {
+			ctx.logger.warn("dsh-plugin-om: 摘要未完成（" + (result.stopReason === "completed" ? "无输出" : String(result.stopReason)) + "），忽略本次摘要");
+			return null;
+		}
+		return text;
+	} catch (error) {
+		/** 错误信息（统一为字符串）。 */
+		const message = error instanceof Error ? error.message : String(error);
+		ctx.logger.warn(`dsh-plugin-om: 摘要子代理失败: ${message}，忽略`);
+		return null;
+	} finally {
+		if (run && typeof run.dispose === "function") try {
+			await run.dispose();
+		} catch {}
+	}
+}
+//#endregion
+//#region src/compress.ts
+/** 历史文本 token 估算：4 字符 ≈ 1 token（与宿主 dsh-token-meter 启发式一致）。 */
+function estimateTextTokens(text) {
+	return Math.ceil(text.length / 4);
+}
+/** 提取 <om-history> 压缩日志消息的内文（去掉标签）；非压缩日志消息返回 undefined。 */
+function historyTextOf(event) {
+	if (event?.type !== "user/message") return void 0;
+	/** 消息纯文本。 */
+	const text = blocksToText(event.data.content);
+	return text.includes(`<om-history>`) ? text.replace(new RegExp(`</?${HISTORY_TAG}>`, "g"), "").trim() : void 0;
+}
+/**
+* 未压缩消息 token 估算：表层节点合计，不含 <om-history> 摘要节点
+* （观察阈值衡量对象）。
+*/
+function measureUncompressedTokens(session, meter) {
+	/** token 合计。 */
+	let total = 0;
+	for (const seq of session.surface.nodes) {
+		/** 当前表层事件（摘要节点不计入未压缩消息）。 */
+		const event = session.events[seq];
+		if (historyTextOf(event) !== void 0) continue;
+		/** 事件对应的消息（用于 token 估算）。 */
+		const message = event ? session.deriveEventMessage(event) : null;
+		total += message ? meter.estimateMessage(message) : 0;
+	}
+	return total;
+}
+/** 定位日志中最后一次 <om-history> 压缩日志（内文 + 事件 seq）；无则 undefined。 */
+function findLatestHistory(session) {
+	/** 会话事件（仅追加，从后向前扫描）。 */
+	const events = session.events;
+	for (let seq = events.length - 1; seq >= 0; seq -= 1) {
+		/** <om-history> 内文（非压缩日志消息时为 undefined）。 */
+		const text = historyTextOf(events[seq]);
+		if (text !== void 0) return {
+			text,
+			seq
+		};
+	}
+}
+/**
+* 观察压缩区间：尾部保留 tailCount 条消息不压缩，区间封顶在最后一个已结束 turn 的
+* 表层节点（fork seed 截断于最后一个 turn/end，当前 turn 消息不可压缩）。
+*/
+function computeCompressRange(session, tailCount) {
+	/** 当前表层节点（按日志顺序）。 */
+	const surface = [...session.surface.nodes];
+	if (surface.length === 0) return void 0;
+	/** 最后一个 turn/end（fork seed 截断于此；无则无可压缩内容）。 */
+	const lastEnd = session.events.findLast((event) => event.type === "turn/end");
+	if (!lastEnd) return void 0;
+	/** seed 覆盖的最后表层节点下标（其后为当前 turn 消息，不可压缩）。 */
+	let seedIdx = -1;
+	for (let i = surface.length - 1; i >= 0; i -= 1) {
+		const node = surface[i];
+		if (node !== void 0 && node <= lastEnd.seq) {
+			seedIdx = i;
+			break;
+		}
+	}
+	if (seedIdx === -1) return void 0;
+	/** 区间末表层节点下标（尾部保留与 seed 封顶取小）。 */
+	const endIdx = Math.min(surface.length - 1 - tailCount, seedIdx);
+	if (endIdx < 0) return void 0;
+	/** 区间起点（表层首节点）。 */
+	const start = surface[0];
+	/** 区间终点（表层节点 seq）。 */
+	const end = surface[endIdx];
+	if (start === void 0 || end === void 0) return void 0;
+	return {
+		start,
+		end,
+		shadowedSeqs: surface.slice(0, endIdx + 1),
+		lastEndSeq: lastEnd.seq
+	};
+}
+/**
+* 中断标记行：范围内 turn/end 以 aborted（含 cause 类型）或 interrupted 结束的轮次
+* （标记用途：让摘要 AI 理解中断原因）。
+*/
+function scanInterruptions(session, fromSeq, toSeq) {
+	/** 标记行缓冲区。 */
+	const marks = [];
+	for (let seq = fromSeq + 1; seq <= toSeq; seq += 1) {
+		/** 当前待检查事件。 */
+		const event = session.events[seq];
+		if (event?.type !== "turn/end") continue;
+		/** 结束原因（判别 kind）。 */
+		const reason = event.data.reason;
+		if (!reason || typeof reason !== "object") continue;
+		if (reason.kind === "aborted") {
+			/** 取消来源（user/parent/hook/disposed；未知标记 unknown）。 */
+			const cause = reason.reason?.kind ?? "unknown";
+			marks.push(`[interrupted] turn ${String(event.data.turn)} 被中断（aborted，原因 ${cause}）`);
+		} else if (reason.kind === "interrupted") marks.push(`[interrupted] turn ${String(event.data.turn)} 因崩溃恢复中断（interrupted）`);
+	}
+	return marks;
+}
+/**
+* 提取遮蔽区间内最后一次 <om-history> 压缩日志（内文 + seq）。
+* 按表层顺序（shadowedSeqs）扫描：单节点替换（反思）后摘要节点 seq 可能大于
+* 被压缩消息的 seq，按 seq 区间扫描会漏（start > end）。
+*/
+function extractHistoryText(session, shadowedSeqs) {
+	/** 区间内找到的最近一次压缩日志。 */
+	let found;
+	for (const seq of shadowedSeqs) {
+		/** <om-history> 内文。 */
+		const text = historyTextOf(session.events[seq]);
+		if (text !== void 0) found = {
+			text,
+			seq
+		};
+	}
+	return found;
+}
+/**
+* message_id 对照表：遮蔽区间内消息事件按表层顺序产出 id 行（插件自产 user/message
+* 如运行时上下文快照与 <om-history> 不入表；观察子会话据此产出正确的 message_id）。
+* 按表层顺序（shadowedSeqs）扫描：与 extractHistoryText 同理，seq 区间扫描会漏。
+*/
+function buildMessageIdTable(session, shadowedSeqs) {
+	/** 对照表行缓冲区。 */
+	const rows = [];
+	for (const seq of shadowedSeqs) {
+		/** 当前待检查事件。 */
+		const event = session.events[seq];
+		if (!event) continue;
+		if (event.type === "user/message") {
+			if (event.data.source?.kind === "plugin") continue;
+			/** 用户消息 id。 */
+			const id = messageIdOfEvent(event);
+			if (id) rows.push(`[user] message_id=${id}`);
+		} else if (event.type === "assistant/message") {
+			/** 助手消息 id。 */
+			const id = messageIdOfEvent(event);
+			if (id) rows.push(`[assistant] message_id=${id}`);
+		} else if (event.type === "tool/result") {
+			/** 结果消息 id。 */
+			const id = messageIdOfEvent(event);
+			if (id) {
+				/** 关联调用 id（供子会话按 callId 定位代码与结果）。 */
+				const callId = String(event.data.message.source.callId ?? "");
+				rows.push(`[tool/result callId=${callId}] message_id=${id}`);
+			}
+		}
+	}
+	return rows;
+}
+/** 追加影子价格认领事件（遮蔽范围 + 遮蔽 seq 列表 + 遮蔽 token 数），返回事件 seq。 */
+function appendClaim(session, data) {
+	return session.append(CLAIM_EVENT, data).seq;
+}
+/** 追加 <om-history> 压缩日志消息（surfaceOp 替换遮蔽区间，source 标记插件来源）。 */
+function appendHistoryMessage(session, content, sourceEventSeqs, surfaceOp) {
+	/** 压缩替换消息（<om-history> 包裹摘要，source 标记插件来源）。 */
+	const message = {
+		id: uuid(),
+		role: "user",
+		content: [{
+			type: "text",
+			text: [
+				"以下是过往会话的压缩日志（<om-history>），为已确立背景：直接继续，不要复述。",
+				"",
+				`<${HISTORY_TAG}>`,
+				content,
+				`</${HISTORY_TAG}>`
+			].join("\n")
+		}],
+		source: {
+			kind: "plugin",
+			plugin: PLUGIN_LABEL
+		}
+	};
+	session.append("user/message", message, {
+		surfaceOp,
+		sourceEventSeqs
+	});
+}
+/**
+* 反思：摘要 tokens ≥ 窗口 × historyMergeRatio 时，fork 子会话精简合并摘要，
+* 替换单个 <om-history> 节点。失败不产生部分替换。
+*/
+async function reflectPass(ctx, agent, config, window, signal) {
+	/** 当前会话。 */
+	const session = agent.session;
+	/** 当前摘要（最后一次 <om-history>；无则跳过）。 */
+	const history = findLatestHistory(session);
+	if (!history) return;
+	/** 反思阈值（窗口 × historyMergeRatio 向下取整）。 */
+	const threshold = Math.floor(window * config.historyMergeRatio);
+	/** 摘要 token 估算。 */
+	const tokens = estimateTextTokens(history.text);
+	if (tokens < threshold) return;
+	/** 摘要节点须仍在表层才可替换。 */
+	if (surfaceIndexOf([...session.surface.nodes], history.seq) === -1) return;
+	/** 反思子会话输出（null 表示失败/跳过）。 */
+	const report = await runSummarySubagent(ctx, agent, REFLECTOR_PERSONA, buildReflectPrompt(), config.compressMaxTokens, signal);
+	if (report === null || report.trim().length === 0) return;
+	try {
+		appendHistoryMessage(session, report, [appendClaim(session, {
+			shadowedRange: {
+				start: history.seq,
+				end: history.seq
+			},
+			shadowedSeqs: [history.seq],
+			shadowedTokenCount: tokens
+		}), history.seq], {
+			op: "replace",
+			start: history.seq,
+			end: history.seq
+		});
+		ctx.logger.info("dsh-plugin-om: 反思完成（摘要 " + tokens + " tokens ≥ 阈值 " + threshold + "，替换摘要节点）");
+	} catch (error) {
+		ctx.logger.warn("dsh-plugin-om: 反思提交失败: " + (error instanceof Error ? error.message : String(error)));
+	}
+}
+/**
+* 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio 时，fork 子会话把未压缩消息压缩为
+* 观察日志，追加到旧摘要并替换被压缩消息区间。失败不产生部分替换。
+*/
+async function observePass(ctx, agent, config, window, tailCount, signal) {
+	/** 当前会话。 */
+	const session = agent.session;
+	/** 观察阈值（窗口 × thresholdRatio 向下取整）。 */
+	const threshold = Math.floor(window * config.thresholdRatio);
+	/** 未压缩消息 token 估算（不含 <om-history> 摘要节点）。 */
+	const uncompressedTokens = measureUncompressedTokens(session, ctx.tokenMeter);
+	if (uncompressedTokens < threshold) return;
+	/** 观察压缩区间（尾部保留 tailCount 条 + seed 封顶；无可行区间则跳过）。 */
+	const range = computeCompressRange(session, tailCount);
+	if (!range) return;
+	/** 区间内旧摘要（追加基准；无则首次压缩）。 */
+	const history = extractHistoryText(session, range.shadowedSeqs);
+	/** 中断标记行。 */
+	const interruptions = scanInterruptions(session, Math.min(...range.shadowedSeqs), range.lastEndSeq);
+	/** 观察提示词。 */
+	const prompt = buildObservePrompt({
+		table: buildMessageIdTable(session, range.shadowedSeqs),
+		interruptions,
+		hasOldHistory: history !== void 0
+	});
+	/** 观察子会话输出（null 表示失败/跳过）。 */
+	const report = await runSummarySubagent(ctx, agent, OBSERVER_PERSONA, prompt, config.compressMaxTokens, signal);
+	if (report === null || report.trim().length === 0) return;
+	/** 合并后的摘要（旧摘要原文保留，新观察日志追加在末尾）。 */
+	const combined = [history?.text, report].filter(Boolean).join("\n");
+	/** 被遮蔽表层节点的 token 估算合计。 */
+	const shadowedTokenCount = range.shadowedSeqs.reduce((total, seq) => {
+		/** 当前表层事件。 */
+		const event = session.events[seq];
+		/** 事件对应的消息（用于 token 估算）。 */
+		const message = event ? session.deriveEventMessage(event) : null;
+		return total + (message ? ctx.tokenMeter.estimateMessage(message) : 0);
+	}, 0);
+	try {
+		appendHistoryMessage(session, combined, [appendClaim(session, {
+			shadowedRange: {
+				start: range.start,
+				end: range.end
+			},
+			shadowedSeqs: range.shadowedSeqs,
+			shadowedTokenCount
+		}), ...range.shadowedSeqs], {
+			op: "replace",
+			start: range.start,
+			end: range.end
+		});
+		ctx.logger.info("dsh-plugin-om: 观察压缩完成（未压缩 " + uncompressedTokens + " tokens ≥ 阈值 " + threshold + "，遮蔽 " + range.shadowedSeqs.length + " 个表层节点，约 " + shadowedTokenCount + " tokens）");
+	} catch (error) {
+		ctx.logger.warn("dsh-plugin-om: 观察压缩提交失败: " + (error instanceof Error ? error.message : String(error)));
+	}
+}
+/**
+* 压力检查 + 两级压缩：先反思（压缩过往摘要，有必要才做），后观察（压缩新消息，
+* 有必要才做）。在 pre-step 阻塞串行执行（避免压缩失败或重复压缩）。仅主会话生效。
+*/
+async function maybeCompress(ctx, agent, config, signal) {
+	/** 当前会话。 */
+	const session = agent.session;
+	/** 会话路由目标（未路由无法查询容量）。 */
+	const target = routedTarget(session);
+	if (target === void 0) return;
+	/** 模型容量信息（contextWindow 决定两级阈值）。 */
+	let info;
+	try {
+		info = await ctx.llm.resolveModelInfo(target.provider, target.model, signal);
+	} catch (error) {
+		ctx.logger.warn("dsh-plugin-om: 解析模型容量失败: " + (error instanceof Error ? error.message : String(error)));
+		return;
+	}
+	/** 模型上下文窗口大小（非法值视为无法压缩）。 */
+	const window = info.context?.contextWindow;
+	if (typeof window !== "number" || !Number.isFinite(window) || window <= 0) return;
+	/** 尾部保留条数（config.tailMessageCount，缺省 10）。 */
+	const tailCount = config.tailMessageCount;
+	await reflectPass(ctx, agent, config, window, signal);
+	await observePass(ctx, agent, config, window, tailCount, signal);
+}
+//#endregion
+//#region src/config.ts
+/**
+* 插件配置：默认值、键校验与合并（preset 行 config 可覆盖全部键）。
+* 手写校验，保持零运行时外部依赖。
+*/
+/** 默认配置（冻结对象，resolveConfig 合并的基底）。 */
+const DEFAULT_CONFIG = Object.freeze({
+	thresholdRatio: .5,
+	historyMergeRatio: .2,
+	compressMaxTokens: 4096,
+	tailMessageCount: 10
+});
+/** 合法配置键集合（未知键直接拒绝）。 */
+const CONFIG_KEYS = /* @__PURE__ */ new Set([
+	"thresholdRatio",
+	"historyMergeRatio",
+	"compressMaxTokens",
+	"tailMessageCount"
+]);
+/** 数值键校验参数表：键名 + [min, max, integer]。 */
+const NUMBER_KEYS = [
+	[
+		"thresholdRatio",
+		.01,
+		1,
+		false
+	],
+	[
+		"historyMergeRatio",
+		.01,
+		1,
+		false
+	],
+	[
+		"compressMaxTokens",
+		1,
+		Infinity,
+		true
+	],
+	[
+		"tailMessageCount",
+		1,
+		Infinity,
+		true
+	]
+];
+/** 归一化原始配置输入：缺省 / null / 空串（含空白串）视为空对象（全部用默认值）。 */
+function normalizeConfigInput(raw) {
+	if (raw === void 0 || raw === null) return {};
+	if (typeof raw === "string" && raw.trim() === "") return {};
+	if (!isRecord(raw)) fail("config must be an object");
+	return raw;
+}
+/**
+* 解析合并配置：校验未知键与数值类型，返回冻结的完整配置。
+* 允许所有配置留空——缺省 / null / 空串的键回退默认值，未给出的键亦取默认值。
+*/
+function resolveConfig(raw) {
+	/** 原始输入（留空视为空对象）。 */
+	const input = normalizeConfigInput(raw);
+	for (const key of Object.keys(input)) if (!CONFIG_KEYS.has(key)) fail(`unknown config key "${key}"`);
+	/** 合并结果（以默认值为基底）。 */
+	const config = { ...DEFAULT_CONFIG };
+	for (const [key, min, max, integer] of NUMBER_KEYS) {
+		/** 该键的原始值（留空则跳过，保持默认值）。 */
+		const value = input[key];
+		if (value === void 0 || value === null) continue;
+		if (typeof value === "string" && value.trim() === "") continue;
+		assertNumber(key, value, {
+			min,
+			max,
+			integer
+		});
+		config[key] = value;
+	}
+	return Object.freeze(config);
+}
+//#endregion
+//#region src/recall.ts
+/**
+* recall 工具：按 message_id 回看原始会话（start_id/end_id 为消息 id，offset 为相对
+* start_id 的消息步数）。recall 自身不设输出上限：超大的工具结果由 tool-result-pruner
+* 裁剪（pruneContent），输出 token 由 pruner 配置控制。
+*
+* 参数由 zod schema（recallArgsSchema）在 execute 入口校验：start_id 必填且非空，
+* end_id/offset 至少提供一个；非法参数抛出可读错误。
+*/
+/**
+* recall 工具参数 schema：start_id 必填且非空；end_id 与 offset 至少提供一个
+* （二者同时给出时 end_id 优先，与 execute 语义一致）；未知键自动剥离。
+*/
+const recallArgsSchema = z.object({
+	start_id: z.string(),
+	end_id: z.string().optional(),
+	offset: z.number().optional()
+}).refine((args) => args.end_id !== void 0 || args.offset !== void 0, { message: "end_id 与 offset 至少提供一个" });
+/**
+* 解析并校验 recall 调用参数：校验失败时抛出首个校验问题的可读消息
+* （普通 Error 而非 ZodError，兼容 SDK 展示）。
+*/
+function parseRecallArgs(raw) {
+	/** safeParse 结果（成功时 data 为 RecallArgs，失败时 error 携带问题列表）。 */
+	const result = recallArgsSchema.safeParse(raw);
+	if (!result.success) throw new Error(result.error.issues.map((issue) => `${issue.path.join(".") || "args"}: ${issue.message}`).join("; "));
+	return result.data;
+}
+/**
+* 构建 recall 工具定义：按 start_id/end_id/offset 定位消息区间并渲染原始内容。
+* getPruner 返回 tool-result-pruner（可选），用于裁剪超大工具结果。
+*/
+function buildRecallTool(getPruner) {
+	return {
+		name: "recall",
+		description: "根据message_id，回看指定区间的过往消息。start_id必须传入，是区间的基准。end_id 和 offset 二选一，end_id 用于指定另一个边界，offset用于指定区间包含的消息数量。",
+		parameters: {
+			start_id: {
+				type: "string",
+				description: "message_id(uuid)，区间的基准边界",
+				required: true
+			},
+			end_id: {
+				type: "string",
+				description: "message_id(uuid)，与 offset 互斥，指定区间的另一个边界。与 start_id 的位置关系不影响结果。"
+			},
+			offset: {
+				type: "number",
+				description: "与 end_id 互斥，指定区间包含的消息数量。传入正数查看start_id之后的若干条消息，负数则是之前的。"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(args, exec) {
+			/** 解析并校验后的调用参数（不满足 schema 时抛出可读错误）。 */
+			const { start_id, end_id, offset } = parseRecallArgs(args);
+			/** 当前会话（缺失则无法回看）。 */
+			const session = exec.agent?.session;
+			if (!session) return "会话异常";
+			if (!isMainSession(session)) return "recall 仅主会话可用";
+			/** 会话消息索引（序列 + byId 映射）。 */
+			const { messages, byId } = indexMessages(session);
+			/** start_id 在消息序列中的下标。 */
+			const startIndex = byId.get(start_id);
+			if (startIndex === void 0) return `start_id "${start_id}" 不存在`;
+			/** 终点下标（end_id 优先，否则 startIndex + offset）。 */
+			let endIndex;
+			if (end_id !== void 0) {
+				/** end_id 在消息序列中的下标。 */
+				const found = byId.get(end_id);
+				if (found === void 0) return `end_id "${end_id}" 不存在`;
+				endIndex = found;
+			} else {
+				/** offset 数值（refine 保证此分支 offset 已提供，schema 保证为 number）。 */
+				const raw = offset ?? 0;
+				endIndex = startIndex + (Number.isFinite(raw) ? Math.floor(raw) : 0);
+			}
+			/** 区间下界（钳制到 [0, len-1]）。 */
+			const lo = Math.max(0, Math.min(startIndex, endIndex));
+			/** 区间上界（钳制到 [0, len-1]）。 */
+			const hi = Math.min(messages.length - 1, Math.max(startIndex, endIndex));
+			/** tool-result-pruner（可选，裁剪超大工具结果）。 */
+			const pruner = getPruner?.();
+			/** 渲染结果缓冲（每条消息一段）。 */
+			const parts = [];
+			for (let i = lo; i <= hi; i += 1) {
+				/** 当前消息节点。 */
+				const node = messages[i];
+				if (!node) continue;
+				/** 节点对应的会话事件。 */
+				const event = session.events[node.seq];
+				if (!event) continue;
+				/** 本条消息的呈现文本。 */
+				let text = "";
+				try {
+					/** 从事件派生的消息对象。 */
+					let message = session.deriveEventMessage(event);
+					if (message && event.type === "tool/result" && pruner?.pruneContent) {
+						/** 裁剪后的内容块（返回 null 表示不裁剪）。 */
+						const pruned = pruner.pruneContent(message.content);
+						if (pruned) message = {
+							...message,
+							content: pruned
+						};
+					}
+					text = message ? renderMessageText(message) : "";
+				} catch {}
+				parts.push(`-- [seq ${node.seq}] ${event.type} --\n${text}`);
+			}
+			if (parts.length === 0) return "指定区间没有消息";
+			return parts.join("\n\n");
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* dsh-plugin-om — Observational Memory（OM）上下文压缩 + recall 检索插件。
+* 不依赖特定 tool mode（native / code / both 均可运行）。
+*
+* 模块：
+*  - recall.ts  recall({ start_id, end_id?, offset? }) 工具：按 message_id 回看原始会话
+*  - compress.ts 自动压缩（OM 观察/反思两级阈值）：pre-step 阻塞串行执行——
+*    反思（摘要 ≥ 窗口 × historyMergeRatio 时 fork 精简合并 <om-history>）、
+*    观察（未压缩消息 ≥ 窗口 × thresholdRatio 时 fork 压缩为观察日志并追加）
+*
+* 约束：不引入自定义会话事件类型——压缩复用宿主已知的 'compaction/prune' 影子价格事件。
+* 仅主会话生效（subagent 不压缩、recall 拒绝）。
+*/
+/** 插件名（Loader 识别入口的稳定标识）。 */
+const name = "dsh-plugin-om";
+/** 插件注入的服务依赖（tools/llm/tokenMeter/sessions），由宿主按序注入。 */
+const inject = [
+	"tools",
+	"llm",
+	"tokenMeter",
+	"sessions"
+];
+/**
+* 插件激活入口：注册 recall 工具，并在 agent/pre-step 阻塞触发两级自动压缩
+* （先反思后观察）。仅主会话生效。
+*/
+function apply(ctx, config) {
+	/** 解析后的插件配置（默认值合并 + 校验）。 */
+	const resolved = resolveConfig(config);
+	ctx.tools.register(buildRecallTool(() => ctx.get("toolResultPruner")));
+	ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
+		try {
+			if (!signal.aborted && isMainSession(agent.session)) await maybeCompress(ctx, agent, resolved, signal);
+		} catch (error) {
+			ctx.logger.warn("dsh-plugin-om: pre-step 处理失败: " + (error instanceof Error ? error.message : String(error)));
+		}
+		return next();
+	});
+}
+//#endregion
+export { apply, inject, name };