@morlay/ui-conversation-message-actions 0.0.18 → 0.0.19-alpha.0

package/src/index.ts

@@ -33,10 +33,12 @@ import {
 } from "./shared.ts";
 import {
   closedTurns,
+  droppedCompactions,
   editableMessages,
   editPlan,
   precedingContentIndex,
   recallBoundary,
+  restoreCompactions,
   retryPlan,
   rerollPlan,
   retryableTurns,
@@ -69,9 +71,9 @@ declare module "@deepseek-ai/cordis" {
 export interface EditorAgent {
   readonly session: Session;
   followup(message: UserMessage): void;
-  /** 等待 agent 到达 quiescence（当前 turn/任务结束后 resolve）。 */
+
   whenIdle(): Promise<void>;
-  // 停止运行中的 loop（上游 Agent.cancel 的 duck-typed 面）；缺省表示实现无取消能力。
+
   cancel?(cause: AgentCancelCause, options?: { keepInbox?: boolean }): void;
 }
 
@@ -154,23 +156,25 @@ function appendManualTurn(
   });
 }
 
+// 边界事件的保留语义（与 session-branch 的 rewind 一致）：turn/end 保留边界事件本身，user/message 丢掉它自己。
+function keepFromOf(events: readonly SessionEvent[], boundary: number): number {
+  if (boundary < 0) return 0;
+  return events[boundary]?.type === "turn/end" ? boundary + 1 : boundary;
+}
+
 async function appendSeedSuffixLive(
   session: Session,
   seedSuffix: readonly SessionEvent[],
   appendDirect: (events: readonly SessionEvent[]) => Promise<void>,
 ): Promise<void> {
   for (const event of seedSuffix) {
-    // 版本效果事件携带 ignorable 标记（上游类型无此字段，duck-type 读取）。
     const ignorable = (event as { ignorable?: boolean }).ignorable === true;
     if (ignorable) {
       const s = session as unknown as {
         log: SessionEvent[];
         eventsSnapshot?: unknown;
       };
-      // 原样存储语义：版本效果事件经 RDB write handle 直接落库（带
-      // ignorable 信封，与 JSONL 一致）。session.append 不保留 ignorable
-      // 标记且类型系统禁止 append 未知类型，因此不发布、直接 push 内存
-      // log（seq 按 log 续接重编号，与 handle cursor 同空间）。
+
       const seq = s.log.length;
       await appendDirect([{ ...event, seq } as SessionEvent]);
       s.log.push({ ...event, seq } as SessionEvent);
@@ -204,8 +208,7 @@ export class SessionEditor extends Service {
 
   constructor(ctx: Context) {
     super(ctx, "sessionEditor");
-    // HTTP 路由随类构造注册（dsh 用 default 类插件，apply 不被调用）；
-    // bundles 顺序保证 webserver 先于本类实例化。
+
     registerHttpRoutes(ctx);
   }
 
@@ -287,14 +290,12 @@ export class SessionEditor extends Service {
         : operation.action === "retry"
           ? retryPlan(operation, turns)
           : rerollPlan(operation, turns);
-    // rewind 前解析模型配置：就地编辑可能截断最后的 request/header
-    // （编辑第一轮 boundary = -1 清空全部），重放 agent 需要 provider/model。
+
     const headerConfig = events.findLast((event) => event.type === "request/header")?.data.header
       .config;
 
     const turnIndex = turns.findIndex((turn) => turn.startSeq === plan.anchorSeq);
-    // 空轮吸收：目标轮之前的空轮（早期重放缺陷的遗留）随截断一并删除，
-    // 重放按保留前缀续号——轮次导航不再出现点不开的空项与轮号空洞。
+
     const preceding = precedingContentIndex(turns, turnIndex);
     const boundary =
       plan.rewindBoundary !== undefined
@@ -302,21 +303,19 @@ export class SessionEditor extends Service {
         : preceding < 0
           ? -1
           : turns[preceding]!.endSeq!;
-    // manualTurn 的轮号同样按保留前缀续号：正常会话等于目标轮号，有空轮
-    // 时收敛为连续编号。
+    // 补回被截断丢掉、但在重放目标之前的压缩
+    const keepFrom = keepFromOf(events, boundary);
+    const compactions = droppedCompactions(events, keepFrom, plan.targetSeq);
+
     const replayTurn = preceding < 0 ? 1 : turns[preceding]!.turn + 1;
 
-    // 派生 seed 后缀：版本效果 + 可选手工回合。版本事件对核心是 ignorable，
-    // 保证非 branch 读者可安全跳过。
-    const seedSuffix: SessionEvent[] = [];
-    appendLogSeedEvent(seedSuffix, "session-branch/version", plan.version, true);
+    const versionSeed: SessionEvent[] = [];
+    appendLogSeedEvent(versionSeed, "session-branch/version", plan.version, true);
+    const manualSeed: SessionEvent[] = [];
     if (plan.manualTurn !== undefined) {
-      appendManualTurn(seedSuffix, { ...plan.manualTurn, turn: replayTurn });
+      appendManualTurn(manualSeed, { ...plan.manualTurn, turn: replayTurn });
     }
 
-    // 就地编辑：不创建新会话、不改变 id。需要重放排队输入时，先在 rewind
-    // 前确保 agent 就绪（cold 先 resume；live 复用驻留 agent）——rewind 截断后
-    // agent 无法再以完整会话 resume，且重放失败不应让截断静默丢弃内容。
     const replay = await this.prepareReplay(
       operation.sessionId,
       plan.queuedUsers,
@@ -324,64 +323,20 @@ export class SessionEditor extends Service {
       headerConfig,
     );
 
-    // rewind 前必须停止运行中的 loop：截断会重写 agent 的 session 内存 log。
     await this.stopLoop(operation.sessionId, signal);
     const live = this.ctx.sessions.get(operation.sessionId);
     await this.ctx.sessionBranch.rewind(operation.sessionId, boundary, signal);
-    if (seedSuffix.length > 0) {
-      if (live !== undefined) {
-        // live：版本效果经 RDB write handle 直接落库（带 ignorable 信封，
-        // 与 JSONL 一致）、manualTurn 走 append；同步 cursor 后显式 flush
-        // （直接落库不发布、不进缓冲，cursor 会落后）。
-        const persistence = this.ctx.sessionPersistence as unknown as {
-          tracker: {
-            writerOf(id: SessionId):
-              | {
-                  append(events: readonly SessionEvent[]): Promise<void>;
-                }
-              | undefined;
-          };
-        };
-        const handle = persistence.tracker.writerOf(operation.sessionId);
-        if (handle === undefined) {
-          throw new Error(
-            `session "${operation.sessionId}" has no live write handle for the version effect`,
-          );
-        }
-        // rewind 截断后可能已追加事件（如 inbox 取消 splice），它们仍在
-        // write-behind 缓冲里；直接对 handle 写版本效果前必须先把缓冲落盘，
-        // 否则 handle cursor 落后于 log 长度 → append seq mismatch。
-        await this.ctx.sessions.flush(live);
-        await appendSeedSuffixLive(live, seedSuffix, (events) => handle.append(events));
-        await this.ctx.sessions.flush(live);
-      } else {
-        // cold：续写 seq 从平衡后的保留前缀接续（exclusive 截断可能残留
-        // 孤儿 step/start，落盘 log 对 token meter 重放非法）。
-        const rawKeepLength = boundary + (plan.rewindBoundary === undefined ? 1 : 0);
-        const keepLength = balanceRewindPrefix(events.slice(0, rawKeepLength)).length;
-        const renumbered = seedSuffix.map(
-          (event, index) =>
-            ({
-              ...event,
-              seq: keepLength + index,
-            }) as SessionEvent,
-        );
-        const handle = await this.ctx.sessionPersistence.open(operation.sessionId, "write");
-        try {
-          await handle.append(renumbered);
-        } finally {
-          await handle.close();
-        }
-      }
-    }
+    // 补回的压缩落在版本效果之后、重放的输入之前
+    const seedStart = this.seedStart(live, events, keepFrom);
+    const seedSuffix: SessionEvent[] = [
+      ...versionSeed,
+      ...restoreCompactions(compactions, keepFrom, seedStart + versionSeed.length),
+      ...manualSeed,
+    ];
+    await this.appendSeedSuffix(operation.sessionId, live, seedSuffix, events, keepFrom);
 
-    // 发起新的 user prompt：把排队输入交给就绪的 agent（rewind 后其 session
-    // 已被截断，followup 基于截断后历史开新轮重放）。无 agent（agents 服务
-    // 缺失）时退化为已 durable 的就地版本。
     let queuedTurns = 0;
     if (replay.agent !== undefined && plan.queuedUsers.length > 0) {
-      // seedSuffix 里的 manualTurn 直接写入了 turn/start，而 agent 的轮次
-      // 游标仍停在 rewind 重置的位置；不同步就会把重放开成重复轮号。
       const lastSeedTurn = seedSuffix.findLast((event) => event.type === "turn/start")?.data.turn;
       if (lastSeedTurn !== undefined) {
         const phase = (replay.agent as unknown as { phase?: { lastTurn?: number } }).phase;
@@ -394,19 +349,11 @@ export class SessionEditor extends Service {
     return {
       sessionId: operation.sessionId,
       queuedTurns,
-      // 操作后是否仍有 live owner（prepareReplay 可能 resume 出 agent）。
+
       live: this.ctx.sessions.get(operation.sessionId) !== undefined,
     };
   }
 
-  /**
-   * 撤回（recall）：只 rewind 截断，不重写、不重放——被撤回的 user 消息文本
-   * 由客户端回填到输入框，交给用户修改后重新发送。
-   *
-   * 边界见 {@link recallBoundary}：轮首消息整轮截断到前一轮 `turn/end`
-   * （无前轮则 -1），轮内 followup 与轮外 user 消息只截断到该消息本身
-   * （exclusive drop），避免留下悬空 `turn/start` 让下一次发送开到错误轮号。
-   */
   private async recallOperation(
     operation: RecallOperation,
     signal?: AbortSignal,
@@ -414,9 +361,20 @@ export class SessionEditor extends Service {
     signal?.throwIfAborted();
     const events = await this.readEvents(operation.sessionId, signal);
     const boundary = recallBoundary(events, closedTurns(events), operation.eventSeq);
-    // rewind 前必须停止运行中的 loop：截断会重写 agent 的 session 内存 log。
+    // 撤回同样要补回被丢掉、但在撤回目标之前的压缩
+    const keepFrom = keepFromOf(events, boundary);
+    const compactions = droppedCompactions(events, keepFrom, operation.eventSeq);
+
     await this.stopLoop(operation.sessionId, signal);
+    const live = this.ctx.sessions.get(operation.sessionId);
     await this.ctx.sessionBranch.rewind(operation.sessionId, boundary, signal);
+    await this.appendSeedSuffix(
+      operation.sessionId,
+      live,
+      restoreCompactions(compactions, keepFrom, this.seedStart(live, events, keepFrom)),
+      events,
+      keepFrom,
+    );
     return {
       sessionId: operation.sessionId,
       queuedTurns: 0,
@@ -424,9 +382,62 @@ export class SessionEditor extends Service {
     };
   }
 
-  // rewind 前停止运行中的 loop：截断会重写 agent 的 session 内存 log；无
-  // live agent 时跳过，实现无取消能力时退化为等待其自然停下（keepInbox
-  // 保留排队输入，截断后由 rdb 的 live 钩子 durable 取消）。
+  // 种子后缀的起点 seq：live 会话是被截断后的日志长度，cold 会话是配平后的保留前缀长度
+  private seedStart(
+    live: Session | undefined,
+    events: readonly SessionEvent[],
+    keepFrom: number,
+  ): number {
+    return live === undefined
+      ? balanceRewindPrefix(events.slice(0, keepFrom)).length
+      : Number(live.seq);
+  }
+
+  private async appendSeedSuffix(
+    sessionId: SessionId,
+    live: Session | undefined,
+    seedSuffix: readonly SessionEvent[],
+    events: readonly SessionEvent[],
+    keepFrom: number,
+  ): Promise<void> {
+    if (seedSuffix.length === 0) return;
+    if (live !== undefined) {
+      const persistence = this.ctx.sessionPersistence as unknown as {
+        tracker: {
+          writerOf(id: SessionId):
+            | {
+                append(events: readonly SessionEvent[]): Promise<void>;
+              }
+            | undefined;
+        };
+      };
+      const handle = persistence.tracker.writerOf(sessionId);
+      if (handle === undefined) {
+        throw new Error(`session "${sessionId}" has no live write handle for the version effect`);
+      }
+
+      await this.ctx.sessions.flush(live);
+      await appendSeedSuffixLive(live, seedSuffix, (batch) => handle.append(batch));
+      await this.ctx.sessions.flush(live);
+      return;
+    }
+
+    const keepLength = balanceRewindPrefix(events.slice(0, keepFrom)).length;
+    const renumbered = seedSuffix.map(
+      (event, index) =>
+        ({
+          ...event,
+          seq: keepLength + index,
+        }) as SessionEvent,
+    );
+    const handle = await this.ctx.sessionPersistence.open(sessionId, "write");
+    try {
+      await handle.append(renumbered);
+    } finally {
+      await handle.close();
+    }
+  }
+
   private async stopLoop(sessionId: SessionId, signal?: AbortSignal): Promise<void> {
     signal?.throwIfAborted();
     const agents = this.ctx.get("agents") as EditorAgentRegistry | undefined;
@@ -443,8 +454,7 @@ export class SessionEditor extends Service {
   ): Promise<readonly SessionEvent[]> {
     const live = this.ctx.sessions.get(sessionId);
     if (live !== undefined) return live.snapshotEvents();
-    // cold：读原始事件（loadStored 不补 closers）——inspect 会把未闭合 log
-    // 补成闭合，编辑未闭合轮次的 user 消息会走错边界。
+
     const branch = this.ctx.sessionBranch as unknown as {
       readRawEvents(
         id: SessionId,
@@ -454,10 +464,6 @@ export class SessionEditor extends Service {
     return (await branch.readRawEvents(sessionId, signal)).events;
   }
 
-  // rewind 前确保 agent 可驱动重放：cold 会话先 resume 出驻留 agent（此时会话
-  // 完整，resume 的 prepare 不与截断冲突）；live 会话复用驻留 agent，停止其
-  // 运行中的 loop 由 rewind 前的 stopLoop 统一负责。agents 服务缺失或无需
-  // 重放时返回空——调用方退化为就地截断版本。
   private async prepareReplay(
     sessionId: SessionId,
     queuedUsers: readonly UserMessage[],
@@ -470,16 +476,12 @@ export class SessionEditor extends Service {
     if (agents === undefined) return { agent: undefined };
     const existing = agents.get(sessionId);
     if (existing !== undefined) {
-      // 排队输入由 rewind 在截断后强制 durable 取消（session-rdb 的
-      // LiveSessionHooks.inbox.clear），这里只需复用驻留 agent。
       return { agent: existing };
     }
-    // cold：resume 已持久化会话（create 会因「已存在持久化日志」失败）。
-    // resume 失败是硬错误：rewind 尚未发生，编辑保持原子（不截断不丢数据）。
+
     const provider = headerConfig?.provider ?? "";
     const model = headerConfig?.model ?? "";
     if (provider.length === 0 || model.length === 0) {
-      // 兜底：从当前会话 events 解析（headerConfig 未提供时）。
       const events = await this.readEvents(sessionId, signal);
       const config = events.findLast((event) => event.type === "request/header")?.data.header
         .config;
@@ -506,11 +508,6 @@ export class SessionEditor extends Service {
 
 export default SessionEditor;
 
-// ---------------------------------------------------------------------------
-// HTTP 面（host）：GET /session-editor（timeline 投影）/ POST /session-editor
-// （edit | reroll | retry | rewind | fork）。
-// ---------------------------------------------------------------------------
-
 interface HttpRequestLike {
   method?: string;
   url?: string;
@@ -733,8 +730,6 @@ async function handleRoute(
 }
 
 function registerHttpRoutes(ctx: Context): void {
-  // web 模式：注册到 webServer（dsh web 的 HTTP 面）。服务在构造期可能
-  // 尚未就绪，effect 回调在插件激活后执行，此时 ctx.get 才能取到。
   ctx.effect(() => {
     const webServer = ctx.get("webServer") as HttpServerLike | undefined;
     if (webServer === undefined) return () => {};
@@ -745,10 +740,7 @@ function registerHttpRoutes(ctx: Context): void {
       handler: (request, response) => handleRoute(editor, request, response),
     });
   }, "session-editor: HTTP route");
-  // desktop 模式：注册到 connection 的共享 /api 通道（官方 desktop 禁用
-  // webserver，走 connection 网关；路径带 /api 前缀）。connection 是可选
-  // 服务（web 模式无），且可能在 SessionEditor 构造前已 provide（事件已
-  // 错过）——监听 internal/service 事件并立即检查一次。
+
   const registerConnectionRoute = (): void => {
     const connection = ctx.get("connection", false) as
       | {
@@ -781,7 +773,6 @@ function registerHttpRoutes(ctx: Context): void {
   registerConnectionRoute();
 }
 
-/** connection.fetch 路由的 Fetch 形态处理（与 webServer 的 node:http 形态同语义）。 */
 async function handleFetchRoute(editor: SessionEditor, request: Request): Promise<Response> {
   try {
     if (request.method === "GET") {

package/src/plan.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { AssistantMessage, ContentBlock, UserMessage } from "@deepseek-ai/dsh-llm";
+import { SessionSeq } from "@deepseek-ai/dsh-session";
 import type { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
 import {
   SESSION_BRANCH_VERSION_SCHEMA,
@@ -24,7 +25,7 @@ export interface ClosedTurn {
 
   closed: boolean;
   user?: SessionEvent<"user/message">;
-  /** 轮内全部 user/message（agent 运行中 followup 追加的输入也计入）。 */
+
   users: SessionEvent<"user/message">[];
   assistants: SessionEvent<"assistant/message">[];
 }
@@ -38,6 +39,9 @@ export interface OperationPlan {
   manualTurn?: { turn: number; user: UserMessage; assistant: AssistantMessage };
 
   queuedUsers: UserMessage[];
+
+  // 操作目标事件（被重放或撤回的那条）的 seq
+  targetSeq: number;
 }
 
 function isTextualBlock(
@@ -88,8 +92,6 @@ export function closedTurns(events: readonly SessionEvent[]): ClosedTurn[] {
     }
     if (current === undefined) continue;
     if (event.type === "user/message" && event.data.source.kind === "user") {
-      // 轮内全部 user/message 都记录：agent 运行中 followup 追加的输入
-      // （第二条及之后）也是已落定文本，可编辑。
       if (current.user === undefined) current.user = event;
       current.users.push(event);
       continue;
@@ -103,8 +105,7 @@ export function closedTurns(events: readonly SessionEvent[]): ClosedTurn[] {
       current = undefined;
     }
   }
-  // 未闭合轮次（无 turn/end）也保留：user 消息已落定，编辑时 rewind 到该
-  // 消息（exclusive drop）重放即可。
+
   if (current !== undefined) result.push({ ...current, closed: false });
   return result;
 }
@@ -126,7 +127,7 @@ export function editableMessages(turns: readonly ClosedTurn[]): EditableMessageB
         });
       }
     }
-    // 未闭合轮次的助手消息是流式 partial，不可编辑。
+
     if (!turn.closed) continue;
     for (const event of turn.assistants) {
       for (const [blockIndex, block] of event.data.message.content.entries()) {
@@ -148,7 +149,6 @@ export function editableMessages(turns: readonly ClosedTurn[]): EditableMessageB
 
 export function retryableTurns(turns: readonly ClosedTurn[]): RetryableTurn[] {
   return turns.flatMap((turn): RetryableTurn[] =>
-    // 未闭合轮次无已落定回复可重生成，不可重试。
     turn.user === undefined || !turn.closed
       ? []
       : [
@@ -162,12 +162,6 @@ export function retryableTurns(turns: readonly ClosedTurn[]): RetryableTurn[] {
   );
 }
 
-/**
- * 目标轮之前最后一个「有内容」轮次的下标：跳过既无用户输入也无助手回复的
- * 空轮。空轮是早期重放缺陷的遗留（turn/start 后直接 turn/end），在轨迹 /
- * 轮次导航里表现为点不开的空项，并让后续轮号出现空洞。rewind 把它们随
- * 目标轮一起截断，重放按保留前缀续号即可自愈。
- */
 export function precedingContentIndex(turns: readonly ClosedTurn[], turnIndex: number): number {
   let index = turnIndex - 1;
   while (index >= 0) {
@@ -184,9 +178,6 @@ export function downstreamUsers(turns: readonly ClosedTurn[], start: number): Us
     .flatMap((turn): UserMessage[] => turn.users.map((user) => cloneUser(user.data)));
 }
 
-// 撤回的 rewind 边界：轮内消息沿用 edit 的轮首规则（轮首整轮截断到前一轮
-// turn/end，无前轮则 -1；轮内 followup 截断到该消息本身），轮外 user 消息按
-// 消息自身位置 exclusive drop（截断该消息及其后全部）。
 export function recallBoundary(
   events: readonly SessionEvent[],
   turns: readonly ClosedTurn[],
@@ -263,17 +254,13 @@ export function editPlan(operation: EditOperation, turns: readonly ClosedTurn[])
       event.data,
       replaceTextBlock(event.data.content, operation.blockIndex, operation.text),
     );
-    // 轮内后续 user/message（agent 运行中 followup 追加的输入）是已落定
-    // 输入：rewind 会 drop 它们，重放时保留（truncate 只截断回复，不丢输入）。
+
     const userIndex = turn.users.findIndex((candidate) => candidate.seq === event.seq);
     const sameTurnFollowups = turn.users.slice(userIndex + 1).map((user) => cloneUser(user.data));
     const later = operation.cascade === "preserve" ? downstreamUsers(turns, turnIndex + 1) : [];
     return {
       anchorSeq: turn.startSeq,
-      // 轮首 user 编辑：整轮截断重放（rewind 到前一轮 turn/end），重放复用
-      // 目标轮号；未闭合轮同样整轮截断——保留悬空的 turn/start 会让重放
-      // 开到下一轮，轮号对不上。轮内 followup 只 rewind 到该消息本身
-      // （exclusive drop），保留轮内已落定的前置输入与回复。
+
       ...(userIndex === 0 ? {} : { rewindBoundary: event.seq }),
       version: pairVersionEffect(operation.sessionId, {
         operation: "edit",
@@ -286,10 +273,10 @@ export function editPlan(operation: EditOperation, turns: readonly ClosedTurn[])
         after: operation.text,
       }),
       queuedUsers: [edited, ...sameTurnFollowups, ...later],
+      targetSeq: event.seq,
     };
   }
 
-  // 未闭合轮次的助手消息是流式 partial，无最终内容可编辑。
   if (!turn.closed)
     throw new SessionBranchError("未闭合轮次的助手消息不可编辑。", "INVALID_BOUNDARY");
   const before = event.data.message.content[operation.blockIndex];
@@ -317,6 +304,7 @@ export function editPlan(operation: EditOperation, turns: readonly ClosedTurn[])
       assistant: assistantReplacement(event, operation.blockIndex, operation.text),
     },
     queuedUsers: operation.cascade === "preserve" ? downstreamUsers(turns, turnIndex + 1) : [],
+    targetSeq: event.seq,
   };
 }
 
@@ -337,6 +325,7 @@ export function retryPlan(operation: RetryOperation, turns: readonly ClosedTurn[
       operation.cascade === "preserve"
         ? downstreamUsers(turns, turnIndex)
         : turn.users.map((user) => cloneUser(user.data)),
+    targetSeq: turn.user.seq,
   };
 }
 
@@ -346,7 +335,7 @@ export function rerollPlan(
 ): OperationPlan {
   for (let index = turns.length - 1; index >= 0; index -= 1) {
     const turn = turns[index];
-    // 未闭合轮次无已落定的助手回复可重生成。
+
     if (turn?.user === undefined || !turn.closed) continue;
     const target = turn.assistants.findLast((event) =>
       event.data.message.content.some(isTextualBlock),
@@ -361,7 +350,183 @@ export function rerollPlan(
         targetEventSeq: target.seq,
       }),
       queuedUsers: turn.users.map((user) => cloneUser(user.data)),
+      targetSeq: target.seq,
     };
   }
   throw new SessionBranchError("当前会话没有可重生成的已落定助手回复。", "INVALID_BOUNDARY");
 }
+
+export interface CompactionBracket {
+  start: SessionEvent;
+  summary?: SessionEvent;
+  checkpoint: SessionEvent;
+  end: SessionEvent;
+}
+
+const COMPACTION_TYPES: ReadonlySet<string> = new Set([
+  "compaction/start",
+  "compaction/summary",
+  "compaction/end",
+]);
+
+// 本包不加载 compaction 的事件类型增强，按类型字符串与结构性字段读取（与 session-rdb 的 schema、log 同一处理方式）。
+function compactionTypeOf(event: SessionEvent): string | undefined {
+  return COMPACTION_TYPES.has(event.type) ? event.type : undefined;
+}
+
+// 压缩事务的替换消息：compact 插件写入的 surface replace 用户消息（checkpoint）。
+function isCompactionCheckpoint(event: SessionEvent): boolean {
+  if (event.type !== "user/message") return false;
+  const op = (event as unknown as { surfaceOp?: unknown }).surfaceOp;
+  if (typeof op !== "object" || op === null) return false;
+  const source = event.data.source as unknown as { kind?: unknown; plugin?: unknown };
+  return source.kind === "plugin" && source.plugin === "compact";
+}
+
+function compactionBrackets(events: readonly SessionEvent[]): CompactionBracket[] {
+  const brackets: CompactionBracket[] = [];
+  let open: { start: SessionEvent; summary?: SessionEvent; checkpoint?: SessionEvent } | undefined;
+  for (const event of events) {
+    const type = compactionTypeOf(event);
+    if (type === "compaction/start") {
+      open = { start: event };
+      continue;
+    }
+    if (open === undefined) continue;
+    if (type === "compaction/summary") {
+      open.summary = event;
+      continue;
+    }
+    if (type === "compaction/end") {
+      if (open.checkpoint !== undefined) {
+        brackets.push({
+          start: open.start,
+          ...(open.summary === undefined ? {} : { summary: open.summary }),
+          checkpoint: open.checkpoint,
+          end: event,
+        });
+      }
+      open = undefined;
+      continue;
+    }
+    if (isCompactionCheckpoint(event)) open.checkpoint = event;
+  }
+  return brackets;
+}
+
+// 截断丢掉、但仍在重放目标之前的完整压缩事务。
+export function droppedCompactions(
+  events: readonly SessionEvent[],
+  keepFrom: number,
+  targetSeq: number,
+): CompactionBracket[] {
+  return compactionBrackets(events).filter(
+    (bracket) => bracket.start.seq >= keepFrom && bracket.end.seq < targetSeq,
+  );
+}
+
+function replacementRange(event: SessionEvent): { start: number; end: number } | undefined {
+  const op = (
+    event as unknown as { surfaceOp?: { op?: unknown; startSeq?: unknown; endSeq?: unknown } }
+  ).surfaceOp;
+  if (op?.op !== "replace") return undefined;
+  if (typeof op.startSeq !== "number" || typeof op.endSeq !== "number") return undefined;
+  return { start: op.startSeq, end: op.endSeq };
+}
+
+function numberList(value: unknown): number[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is number => typeof item === "number")
+    : [];
+}
+
+// 把截断丢掉的压缩重排到 base 起的连续 seq：standalone 形态（不属于任何 turn，与手动 /compact 一致），
+// 摘要替换引用的 seq 同步重编号（保留前缀内的 seq 不变），metering 事件与替换消息保持相邻。
+export function restoreCompactions(
+  brackets: readonly CompactionBracket[],
+  keepFrom: number,
+  base: number,
+): SessionEvent[] {
+  const moved = new Map<number, number>();
+  const resolve = (seq: number): number | undefined => (seq < keepFrom ? seq : moved.get(seq));
+  const resolveAll = (seqs: readonly number[]): number[] | undefined => {
+    const resolved: number[] = [];
+    for (const seq of seqs) {
+      const next = resolve(seq);
+      if (next === undefined) return undefined;
+      resolved.push(next);
+    }
+    return resolved;
+  };
+
+  const restored: SessionEvent[] = [];
+  for (const bracket of brackets) {
+    const range = replacementRange(bracket.checkpoint);
+    const shadowedSeqs = resolveAll(
+      numberList((bracket.summary?.data as { shadowedSeqs?: unknown } | undefined)?.shadowedSeqs),
+    );
+    const start = range === undefined ? undefined : resolve(range.start);
+    const end = range === undefined ? undefined : resolve(range.end);
+    // 引用了被丢弃事件的压缩无法重建替换范围，只能一并丢弃
+    if (start === undefined || end === undefined || shadowedSeqs === undefined) continue;
+
+    const at = base + restored.length;
+    const summary = bracket.summary;
+    const checkpointSeq = at + (summary === undefined ? 1 : 2);
+    moved.set(bracket.start.seq, at);
+    if (summary !== undefined) moved.set(summary.seq, at + 1);
+    moved.set(bracket.checkpoint.seq, checkpointSeq);
+    moved.set(bracket.end.seq, checkpointSeq + 1);
+
+    // 引用自身事务的事件按新位置重算：开标记、metering 事件、替换范围内的 surface 节点
+    const sources = [at, ...(summary === undefined ? [] : [at + 1]), ...shadowedSeqs];
+    restored.push(
+      standaloneCompaction(bracket.start, at),
+      ...(summary === undefined
+        ? []
+        : [meteringShadowPrice(summary, at + 1, { start, end }, shadowedSeqs)]),
+      replacementCheckpoint(bracket.checkpoint, checkpointSeq, { start, end }, sources),
+      standaloneCompaction(bracket.end, checkpointSeq + 1),
+    );
+  }
+  return restored;
+}
+
+function standaloneCompaction(event: SessionEvent, seq: number): SessionEvent {
+  return {
+    ...event,
+    seq: SessionSeq(seq),
+    data: { ...event.data, turn: null },
+  } as unknown as SessionEvent;
+}
+
+function meteringShadowPrice(
+  event: SessionEvent,
+  seq: number,
+  range: { start: number; end: number },
+  shadowedSeqs: readonly number[],
+): SessionEvent {
+  return {
+    ...event,
+    seq: SessionSeq(seq),
+    data: {
+      ...event.data,
+      shadowedRange: { start: range.start, end: range.end },
+      shadowedSeqs: [...shadowedSeqs],
+    },
+  } as unknown as SessionEvent;
+}
+
+function replacementCheckpoint(
+  event: SessionEvent,
+  seq: number,
+  range: { start: number; end: number },
+  sources: readonly number[],
+): SessionEvent {
+  return {
+    ...event,
+    seq: SessionSeq(seq),
+    surfaceOp: { op: "replace", startSeq: range.start, endSeq: range.end },
+    sourceEventSeqs: [...sources],
+  } as unknown as SessionEvent;
+}