@downcity/agent 1.1.438 → 1.1.445

package/src/session/{SessionMessages.ts → messages/SessionMessages.ts}

@@ -9,46 +9,43 @@
 import { generate_id } from "@/utils/Id.js";
 import { SessionAgentMessageWriter } from "@/session/messages/SessionAgentMessageWriter.js";
 import { SessionAgentMessageState } from "@/session/messages/SessionAgentMessageState.js";
-import { SessionAgentActionPartWriter } from "@/session/messages/SessionAgentActionPartWriter.js";
 import {
   has_assistant_result_content,
-  normalize_canonical_session_user_parts,
   normalize_session_user_parts,
 } from "@/session/messages/SessionUserMessage.js";
 import type { JsonObject } from "@downcity/type";
 import type {
   ListSessionMessagesInput,
+  SessionActionStatus,
   SessionAgentActionPart,
   SessionAgentErrorPart,
-  SessionAgentInteractionPart,
+  SessionAgentInteraction,
   SessionAgentMessage,
-  SessionAgentMessagePart,
   SessionMessage,
   SessionMessagePage,
   SessionUserMessage,
   SessionUserMessagePart,
 } from "@downcity/type";
-import type {
-  SessionMutation,
-  SessionMessageMutation as SessionMessageSnapshotMutation,
-} from "@downcity/type";
+import { SessionMessageCache } from "@/session/messages/SessionMessageCache.js";
+import { resolve_session_message_state } from "@/session/messages/SessionMessageState.js";
+import {
+  next_agent_part_sequence,
+  resolve_changed_agent_parts,
+} from "@/session/messages/SessionAgentParts.js";
 import type { SessionMessageStorageStats } from "@/types/store/SessionStorage.js";
-import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
 import type {
   SessionInteractionCloseInput,
   SessionInteractionRequest,
   SessionInteractionResponse,
 } from "@downcity/type";
 import type { SessionActionEvent } from "@downcity/type";
-import { persist_user_prompt_file_parts } from "@executor/messages/SessionAttachmentMapper.js";
+import { persist_user_prompt_file_parts } from "@/model/messages/SessionAttachmentMapper.js";
 import type {
-  AppendCompletedAgentMessageInput,
   AppendExternalSessionAgentMessageInput,
   AppendExternalSessionUserMessageInput,
   AppendSessionAgentErrorPartInput,
   AppendSessionPromptMessageInput,
   AppendSessionUserMessageInput,
-  OpenSessionAgentActionPartInput,
   OpenSessionAgentMessageInput,
   SessionMessagesOptions,
 } from "@/types/session/SessionMessages.js";
@@ -56,7 +53,6 @@ import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
 export { SessionAgentMessageWriter } from "@/session/messages/SessionAgentMessageWriter.js";
-export { SessionAgentActionPartWriter } from "@/session/messages/SessionAgentActionPartWriter.js";
 export { normalize_session_user_parts } from "@/session/messages/SessionUserMessage.js";
 
 /** 唯一 Session Message 写入服务。 */
@@ -64,8 +60,8 @@ export class SessionMessages {
   readonly session_id: string;
   private readonly store: SessionStorage;
   private readonly attachment_store: SessionAttachmentStore;
-  private readonly publish: SessionMessagesOptions["publish"];
-  private readonly messages_by_id = new Map<string, SessionMessage>();
+  /** Message 运行缓存与 Mutation 发布边界。 */
+  private readonly cache: SessionMessageCache;
   /** Assistant 草稿与 Interaction 的串行状态转换器。 */
   private readonly agent_state: SessionAgentMessageState;
   /** 当前 Message 恢复事务；并发初始化共享同一个 Promise。 */
@@ -75,19 +71,23 @@ export class SessionMessages {
     this.session_id = String(options.session_id || "").trim();
     this.store = options.store;
     this.attachment_store = options.attachment_store;
-    this.publish = options.publish;
     if (!this.session_id) throw new Error("SessionMessages requires session_id");
+    this.cache = new SessionMessageCache({
+      session_id: this.session_id,
+      publish: options.publish,
+    });
     this.agent_state = new SessionAgentMessageState({
       session_id: this.session_id,
       store: this.store,
-      list_messages: () => this.messages_by_id.values(),
-      accept_message: (message, publish_mutation) =>
-        this.accept_message(message, publish_mutation),
-      project_mutation: (mutation, message) =>
-        this.accept_mutation(mutation, message),
+      cache: this.cache,
     });
   }
 
+  /** 该 Message 是否仍由未收口的 writer 持有；终态推导与 Action 归属共同依赖它。 */
+  private is_held_by_writer(message_id: string): boolean {
+    return this.cache.is_held(message_id);
+  }
+
   /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
   async initialize(): Promise<void> {
     if (!this.initialize_promise) {
@@ -108,9 +108,7 @@ export class SessionMessages {
   private async restore_messages(): Promise<void> {
     await this.store.initialize();
     const persisted_messages = await this.store.list_recoverable_agent_messages();
-    this.messages_by_id.clear();
     for (const message of persisted_messages) {
-      this.remember_message(message);
       const updated_at = Date.now();
       const recovered: SessionAgentMessage = {
         ...message,
@@ -125,23 +123,31 @@ export class SessionMessages {
               description: part.description || "Action interrupted before completion.",
             };
           }
-          if (part.type === "interaction" && part.status === "pending") {
-            return {
-              ...part,
-              status: "cancelled" as const,
-              cancel_reason: "runtime_interrupted" as const,
-              resolved_at: updated_at,
-            };
-          }
-          if (
-            part.type === "tool" &&
-            part.state !== "completed" &&
-            part.state !== "failed"
-          ) {
+          if (part.type === "tool") {
+            const existing_interactions = part.interactions ?? [];
+            const had_pending_interaction = existing_interactions.some(
+              (interaction) => interaction.status === "pending",
+            );
+            const interactions = had_pending_interaction
+              ? existing_interactions.map((interaction) =>
+                  interaction.status === "pending"
+                    ? {
+                        ...interaction,
+                        status: "cancelled" as const,
+                        cancel_reason: "runtime_interrupted" as const,
+                        resolved_at: updated_at,
+                      }
+                    : interaction,
+                )
+              : part.interactions;
+            if (part.state === "completed" || part.state === "failed") {
+              return had_pending_interaction ? { ...part, interactions } : part;
+            }
             return {
               ...part,
               state: "failed" as const,
               error: "Tool interrupted before completion.",
+              interactions,
             };
           }
           if (
@@ -153,10 +159,7 @@ export class SessionMessages {
           return part;
         }), {
           part_id: `error:${generate_id()}`,
-          sequence: message.parts.reduce(
-            (sequence, part) => Math.max(sequence, part.sequence + 1),
-            1,
-          ),
+          sequence: next_agent_part_sequence(message.parts),
           type: "error",
           scope: message.turn_id ? "turn" : "session",
           code: "runtime_interrupted",
@@ -164,19 +167,20 @@ export class SessionMessages {
           recoverable: true,
         }],
       };
-      const changed_parts = resolve_changed_agent_parts(message, recovered);
+      const changed_parts = resolve_changed_agent_parts(message.parts, recovered.parts);
       await this.store.update_message({
         message: recovered,
         expected_revision: message.revision,
         changed_parts,
       });
-      this.accept_message(recovered, false);
+      // 恢复不属于本次订阅范围，只更新内存事实，不发布 Mutation。
+      this.cache.accept(recovered, false);
     }
   }
 
   /** 同步读取当前内存 Message。 */
   get_message(message_id: string): SessionMessage | undefined {
-    return this.messages_by_id.get(message_id);
+    return this.cache.get(message_id);
   }
 
   /** 追加一条 canonical User Message。 */
@@ -196,52 +200,52 @@ export class SessionMessages {
       created_at,
       updated_at: created_at,
       role: "user",
-      parts: normalize_canonical_session_user_parts(input.parts).map((part) => ({
-        ...part,
-        part_id: `${message_id}:part:${String(part.sequence)}`,
+      // 调用方只提供内容；part_id 是全局主键，必须在这里统一分配。
+      parts: input.parts.map((part, index) => ({
+        ...structuredClone(part),
+        sequence: index + 1,
+        part_id: `${message_id}:part:${String(index + 1)}`,
       })),
     }));
-    return message as SessionUserMessage;
+    if (message.role !== "user") {
+      throw new Error(`User Message expected: ${message.message_id}`);
+    }
+    return message;
   }
 
   /** 创建可持续接收 chunk 的 Assistant Message。 */
   async open_agent_message(
     input: OpenSessionAgentMessageInput,
   ): Promise<SessionAgentMessageWriter> {
-    const message = (await this.create_message((sequence, created_at) => ({
-      message_id:
-        String(input.message_id || "").trim() ||
-        `agent:${this.session_id}:${generate_id()}`,
-      session_id: this.session_id,
-      turn_id: input.turn_id,
-      sequence,
-      revision: 1,
-      visibility: input.visibility || "visible",
-      created_at,
-      updated_at: created_at,
-      role: "agent",
-      state: "streaming",
-      parts: [],
-    }), true)) as SessionAgentMessage;
-    return new SessionAgentMessageWriter(this, message.message_id);
-  }
-
-  /** 直接写入一条已完成 Assistant Message。 */
-  async append_completed_agent_message(
-    input: AppendCompletedAgentMessageInput,
-  ): Promise<SessionAgentMessage> {
-    const turn_id = input.turn_id || `external:${this.session_id}:${generate_id()}`;
-    const writer = await this.open_agent_message({
-      turn_id,
-      visibility: input.visibility || "visible",
+    const message_id =
+      String(input.message_id || "").trim() ||
+      `agent:${this.session_id}:${generate_id()}`;
+    // 先建立持有关系，创建消息时的首次接受才会被登记为可写 Message。
+    const writer = new SessionAgentMessageWriter({
+      message_id,
+      state: this.agent_state,
+      cache: this.cache,
     });
-    for (const part of input.parts) await writer.upsert_part(part);
-    await writer.complete();
-    const message = await this.store.read_message(writer.message_id);
-    if (!message || message.role !== "agent") {
-      throw new Error(`Completed Agent Message not found: ${writer.message_id}`);
+    this.cache.set_held(message_id);
+    try {
+      await this.create_message((sequence, created_at) => ({
+        message_id,
+        session_id: this.session_id,
+        turn_id: input.turn_id,
+        sequence,
+        revision: 1,
+        visibility: input.visibility || "visible",
+        created_at,
+        updated_at: created_at,
+        role: "agent",
+        state: "streaming",
+        parts: [],
+      }), true);
+    } catch (error) {
+      this.cache.release_held(message_id);
+      throw error;
     }
-    return message;
+    return writer;
   }
 
   /** 把公开 Session API 的 User 输入转换为 canonical Message 并持久化。 */
@@ -302,27 +306,35 @@ export class SessionMessages {
     return await this.store.read_latest_agent_message(turn_id);
   }
 
-  /** 按稳定 Action ID 创建或更新只包含 Action Part 的 Agent Message。 */
+  /**
+   * 按稳定 Action ID 落盘一条 canonical Action。
+   *
+   * 判定顺序固定，三分支互斥：
+   * 1. 该 Turn 存在 writer 持有的正文 Message → Action 作为其 Part 内联；
+   * 2. 否则存在 id 等于 action_id 的载体 Message → 原地更新其中的 Action Part；
+   * 3. 否则新建仅含该 Action Part 的载体 Message。
+   *
+   * 三个分支都只写 Part，Message 终态统一由 SessionMessageState 推导。
+   */
   async persist_action(
     event: SessionActionEvent,
     options?: { publish_mutation?: boolean },
   ): Promise<void> {
+    await this.ensure_initialized();
     const publish_mutation = options?.publish_mutation !== false;
+    const body = event.turn_id ? this.find_open_message(event.turn_id) : undefined;
+    if (body) {
+      await this.agent_state.commit_parts(
+        body.message_id,
+        [this.resolve_streaming_action_part(body, event)],
+        { publish_mutation },
+      );
+      return;
+    }
     const existing = this.get_message(event.action_id) ||
       await this.store.read_message(event.action_id) || undefined;
     if (!existing) {
-      const writer = await this.open_action_part({
-        message_id: event.action_id,
-        turn_id: event.turn_id,
-        action_type: event.action_type,
-        title: event.title,
-        description: event.description,
-        publish_mutation,
-      });
-      if (event.status === "completed") await writer.complete();
-      if (event.status === "failed") {
-        await writer.fail(event.description || event.title);
-      }
+      await this.create_standalone_action_message(event, publish_mutation);
       return;
     }
     if (existing.role === "agent" && event.status !== "running") {
@@ -333,41 +345,72 @@ export class SessionMessages {
     }
   }
 
-  /** 创建只包含 running Action Part 的 Agent Message。 */
-  async open_action_part(
-    input: OpenSessionAgentActionPartInput,
-  ): Promise<SessionAgentActionPartWriter> {
-    const message_id =
-      String(input.message_id || "").trim() ||
-      `agent-action:${this.session_id}:${generate_id()}`;
-    const message = (await this.create_message((sequence, created_at) => ({
-      message_id,
+  /** 查找指定 Turn 当前由 writer 持有的正文 Message（同一时刻至多一条）。 */
+  private find_open_message(turn_id: string): SessionAgentMessage | undefined {
+    const message_id = this.cache.held_message_id();
+    if (!message_id) return undefined;
+    const message = this.get_message(message_id);
+    if (!message || message.role !== "agent" || message.turn_id !== turn_id) {
+      return undefined;
+    }
+    return message;
+  }
+
+  /** 复用已有 Action Part 身份，为被 writer 持有的 Agent Message 构造对齐的 Action Part。 */
+  private resolve_streaming_action_part(
+    target: SessionAgentMessage,
+    event: SessionActionEvent,
+  ): SessionAgentActionPart {
+    const part_id = `action-part:${event.action_id}`;
+    const existing = target.parts.find(
+      (part): part is SessionAgentActionPart =>
+        part.type === "action" && part.part_id === part_id,
+    );
+    return create_action_part({
+      action_id: event.action_id,
+      part_id,
+      sequence: existing?.sequence ?? next_agent_part_sequence(target.parts),
+      action_type: event.action_type,
+      state: event.status,
+      title: event.title,
+      description: event.description,
+    });
+  }
+
+  /**
+   * 创建只包含单个 Action Part 的独立 Agent Message。
+   *
+   * 只在当前 Turn 没有 writer 持有的 Agent Message 时使用；Action Part 直接以事件声明的
+   * 目标状态落盘，不再先建后改，避免同一个 Action 产生两次 Mutation。
+   */
+  private async create_standalone_action_message(
+    event: SessionActionEvent,
+    publish_mutation: boolean,
+  ): Promise<void> {
+    const description = event.description ??
+      (event.status === "failed" ? event.title : undefined);
+    const parts = [create_action_part({
+      action_id: event.action_id,
+      part_id: `action-part:${event.action_id}`,
+      sequence: 1,
+      action_type: event.action_type,
+      state: event.status,
+      title: event.title,
+      ...(description ? { description } : {}),
+    })];
+    await this.create_message((sequence, created_at) => ({
+      message_id: event.action_id,
       session_id: this.session_id,
-      ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+      ...(event.turn_id ? { turn_id: event.turn_id } : {}),
       sequence,
       revision: 1,
       visibility: "visible",
       created_at,
       updated_at: created_at,
       role: "agent",
-      state: "streaming",
-      parts: [{
-        part_id: `action-part:${message_id}`,
-        sequence: 1,
-        type: "action",
-        action_id: message_id,
-        action_type: input.action_type,
-        state: "running",
-        title: input.title,
-        ...(input.description ? { description: input.description } : {}),
-        ...(input.data ? { data: structuredClone(input.data) } : {}),
-      }],
-    }), false, input.publish_mutation !== false)) as SessionAgentMessage;
-    return new SessionAgentActionPartWriter(
-      this,
-      message.message_id,
-      input.publish_mutation !== false,
-    );
+      state: resolve_session_message_state(parts, false),
+      parts,
+    }), event.status === "running", publish_mutation);
   }
 
   /** 更新 Action 状态，同时保持 message_id 与 sequence 不变。 */
@@ -377,9 +420,10 @@ export class SessionMessages {
     changes?: { title?: string; description?: string; data?: JsonObject },
     options?: { publish_mutation?: boolean },
   ): Promise<SessionAgentMessage> {
-    const current_message = require_message([
-      this.get_message(message_id) || await this.store.read_message(message_id),
-    ].filter((message): message is SessionMessage => Boolean(message)), message_id, "agent");
+    const current_message = this.get_message(message_id) || await this.store.read_message(message_id);
+    if (!current_message || current_message.role !== "agent") {
+      throw new Error(`Session agent Message not found: ${message_id}`);
+    }
     const action = current_message.parts.find(
         (part): part is SessionAgentActionPart => part.type === "action",
       );
@@ -393,11 +437,15 @@ export class SessionMessages {
         : {}),
       ...(changes?.data ? { data: structuredClone(changes.data) } : {}),
     };
+    const next_parts = current_message.parts.map((part) =>
+      part.part_id === action.part_id ? next_action : part);
     const message: SessionAgentMessage = {
       ...current_message,
-      state: status === "running" ? "streaming" : "done",
-      parts: current_message.parts.map((part) =>
-        part.part_id === action.part_id ? next_action : part),
+      state: resolve_session_message_state(
+        next_parts,
+        this.is_held_by_writer(message_id),
+      ),
+      parts: next_parts,
       revision: current_message.revision + 1,
       updated_at: Date.now(),
     };
@@ -406,8 +454,8 @@ export class SessionMessages {
       expected_revision: current_message.revision,
       changed_parts: [next_action],
     });
-    this.accept_message(message, options?.publish_mutation !== false);
-    return message as SessionAgentMessage;
+    this.cache.accept(message, options?.publish_mutation !== false);
+    return message;
   }
 
   /**
@@ -432,12 +480,7 @@ export class SessionMessages {
 
     const error_part: SessionAgentErrorPart = {
       part_id: `error:${generate_id()}`,
-      sequence: target
-        ? target.parts.reduce(
-            (sequence, part) => Math.max(sequence, part.sequence + 1),
-            1,
-          )
-        : 1,
+      sequence: target ? next_agent_part_sequence(target.parts) : 1,
       type: "error",
       scope: input.scope,
       code: input.code,
@@ -445,8 +488,7 @@ export class SessionMessages {
       recoverable: input.recoverable,
     };
 
-    if (target?.state === "streaming") {
-      this.remember_message(target);
+    if (target && this.is_held_by_writer(target.message_id)) {
       await this.agent_state.commit_parts(target.message_id, [error_part]);
       const updated = await this.store.read_message(target.message_id);
       if (!updated || updated.role !== "agent") {
@@ -469,11 +511,11 @@ export class SessionMessages {
         expected_revision: target.revision,
         changed_parts: [error_part],
       });
-      this.accept_message(message);
-      return message as SessionAgentMessage;
+      this.cache.accept(message);
+      return message;
     }
 
-    return (await this.create_message((sequence, created_at) => ({
+    const message = await this.create_message((sequence, created_at) => ({
       message_id: `agent:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       ...(input.turn_id ? { turn_id: input.turn_id } : {}),
@@ -483,9 +525,13 @@ export class SessionMessages {
       created_at,
       updated_at: created_at,
       role: "agent",
-      state: "done",
+      state: resolve_session_message_state([error_part], false),
       parts: [error_part],
-    }))) as SessionAgentMessage;
+    }));
+    if (message.role !== "agent") {
+      throw new Error(`Agent Message expected: ${message.message_id}`);
+    }
+    return message;
   }
 
   /** 按 Message sequence 返回一页完整 Message 聚合。 */
@@ -510,10 +556,10 @@ export class SessionMessages {
     const messages = has_more ? page.slice(1) : page;
     const start_sequence = messages[0]?.sequence;
     const end_sequence = messages.at(-1)?.sequence;
-    const stats = await this.store.message_stats();
+    const total = await this.store.message_count();
     return {
       items: messages.map((message) => structuredClone(message)),
-      total: stats.message_count,
+      total,
       ...(start_sequence !== undefined ? { start_sequence } : {}),
       ...(end_sequence !== undefined ? { end_sequence } : {}),
       ...(has_more && start_sequence !== undefined
@@ -566,75 +612,6 @@ export class SessionMessages {
     }
   }
 
-  /** @internal 只向运行投影追加 Agent 文本 delta。 */
-  project_agent_delta(
-    message_id: string,
-    part_id: string,
-    type: "text" | "reasoning",
-    delta: string,
-  ): void {
-    this.agent_state.project_delta(message_id, part_id, type, delta);
-  }
-
-  /** @internal 只向运行投影追加 Agent Tool 输入 delta。 */
-  project_agent_tool_input_delta(
-    message_id: string,
-    part_id: string,
-    tool_call_id: string,
-    delta: string,
-  ): void {
-    this.agent_state.project_delta(
-      message_id,
-      part_id,
-      "tool_input",
-      delta,
-      tool_call_id,
-    );
-  }
-
-  /** @internal 只向运行投影写入 Agent 完整 Part。 */
-  project_agent_part(
-    message_id: string,
-    part: SessionAgentMessagePart,
-  ): void {
-    this.agent_state.project_part(message_id, part);
-  }
-
-  /** @internal 原子提交当前运行投影。 */
-  async checkpoint_agent_message(message_id: string): Promise<void> {
-    await this.agent_state.checkpoint(message_id);
-  }
-
-  /** @internal 原子提交一组非流式 Agent Parts。 */
-  async commit_agent_parts(
-    message_id: string,
-    parts: readonly SessionAgentMessagePart[],
-  ): Promise<void> {
-    await this.agent_state.commit_parts(message_id, parts);
-  }
-
-  /** @internal 丢弃未提交的当前 Step 投影。 */
-  async rollback_agent_projection(message_id: string): Promise<void> {
-    await this.agent_state.rollback_projection(message_id);
-  }
-
-  /** @internal 原子提交当前 Assistant step 的 metadata 快照。 */
-  async commit_agent_step(
-    message_id: string,
-    parts: SessionAgentMessagePart[],
-  ): Promise<void> {
-    await this.agent_state.commit_step(message_id, parts);
-  }
-
-  /** @internal 收口 Assistant Message。 */
-  async complete_agent_message(
-    message_id: string,
-    status: "completed" | "stopped" | "failed",
-    error?: string,
-  ): Promise<void> {
-    await this.agent_state.complete(message_id, status, error);
-  }
-
   private async create_message(
     factory: (sequence: number, created_at: number) => SessionMessage,
     draft = false,
@@ -648,24 +625,19 @@ export class SessionMessages {
       }
       return candidate;
     });
-    this.accept_message(message, publish_mutation);
+    this.cache.accept(message, publish_mutation);
     return message;
   }
 
-  /** 读取当前流式 Assistant 中的指定 Tool Part。 */
-  find_streaming_tool(tool_call_id: string): SessionStreamingToolLocation | undefined {
-    return this.agent_state.find_streaming_tool(tool_call_id);
-  }
-
   /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
-  list_pending_interactions(): SessionAgentInteractionPart[] {
+  list_pending_interactions(): SessionAgentInteraction[] {
     return this.agent_state.list_pending_interactions();
   }
 
   /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
   async request_interaction(
     request: SessionInteractionRequest,
-  ): Promise<SessionAgentInteractionPart> {
+  ): Promise<SessionAgentInteraction> {
     return await this.agent_state.request_interaction(request);
   }
 
@@ -673,7 +645,7 @@ export class SessionMessages {
   async resolve_interaction(
     interaction_id: string,
     response: SessionInteractionResponse,
-  ): Promise<SessionAgentInteractionPart> {
+  ): Promise<SessionAgentInteraction> {
     return await this.agent_state.resolve_interaction(
       interaction_id,
       response,
@@ -684,64 +656,13 @@ export class SessionMessages {
   async close_interaction(
     interaction_id: string,
     input: SessionInteractionCloseInput,
-  ): Promise<SessionAgentInteractionPart> {
+  ): Promise<SessionAgentInteraction> {
     return await this.agent_state.close_interaction(interaction_id, input);
   }
 
-  private build_message_mutation(
-    message: SessionMessage,
-  ): SessionMessageSnapshotMutation {
-    return {
-      mutation_id: generate_id(),
-      variant: "message",
-      role: message.role,
-      message_id: message.message_id,
-      sequence: message.sequence,
-      revision: message.revision,
-      session_id: this.session_id,
-      ...(message.turn_id ? { turn_id: message.turn_id } : {}),
-      created_at: message.updated_at,
-      message,
-    } as SessionMessageSnapshotMutation;
-  }
-
-  private accept_message(message: SessionMessage, publish_mutation = true): void {
-    if (!publish_mutation) {
-      this.remember_message(message);
-      return;
-    }
-    this.accept_mutation(this.build_message_mutation(message), message);
-  }
-
-  private accept_mutation(mutation: SessionMutation, message: SessionMessage): void {
-    this.remember_message(message);
-    this.publish(mutation);
-  }
-
-  /** 仅缓存可变的 streaming Agent Message；终态历史始终读取 SQLite。 */
-  private remember_message(message: SessionMessage): void {
-    this.messages_by_id.delete(message.message_id);
-    if (message.role === "agent" && message.state === "streaming") {
-      this.messages_by_id.set(message.message_id, structuredClone(message));
-    }
-  }
-
   private async ensure_initialized(): Promise<void> {
     await this.initialize();
   }
-
-}
-
-function require_message<TRole extends SessionMessage["role"]>(
-  messages: SessionMessage[],
-  message_id: string,
-  role: TRole,
-): Extract<SessionMessage, { role: TRole }> {
-  const message = messages.find((item) => item.message_id === message_id);
-  if (!message || message.role !== role) {
-    throw new Error(`Session ${role} Message not found: ${message_id}`);
-  }
-  return message as Extract<SessionMessage, { role: TRole }>;
 }
 
 function resolve_import_id(map: Map<string, string>, source_id: string, prefix: string): string {
@@ -752,15 +673,35 @@ function resolve_import_id(map: Map<string, string>, source_id: string, prefix:
   return created;
 }
 
-/** 按真实 Message sequence 升序排序。 */
-function resolve_changed_agent_parts(
-  current: SessionAgentMessage,
-  next: SessionAgentMessage,
-): SessionAgentMessagePart[] {
-  const current_by_id = new Map(
-    current.parts.map((part) => [part.part_id, JSON.stringify(part)]),
-  );
-  return next.parts.filter(
-    (part) => current_by_id.get(part.part_id) !== JSON.stringify(part),
-  );
+/** 构造一个 canonical Action Part。 */
+function create_action_part(input: {
+  /** Action 稳定业务标识。 */
+  action_id: string;
+  /** Part 在所属 Message 内的稳定标识。 */
+  part_id: string;
+  /** Part 在所属 Message 内的顺序号。 */
+  sequence: number;
+  /** Action 业务类别。 */
+  action_type: string;
+  /** Action 生命周期状态。 */
+  state: SessionActionStatus;
+  /** Action 展示标题。 */
+  title: string;
+  /** Action 展示描述。 */
+  description?: string;
+  /** Action 结构化附加数据。 */
+  data?: JsonObject;
+}): SessionAgentActionPart {
+  return {
+    part_id: input.part_id,
+    sequence: input.sequence,
+    type: "action",
+    action_id: input.action_id,
+    action_type: input.action_type,
+    state: input.state,
+    title: input.title,
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.data ? { data: structuredClone(input.data) } : {}),
+  };
 }
+