@downcity/agent 1.1.430 → 1.1.438

package/src/session/SessionMessages.ts

@@ -7,9 +7,9 @@
  */
 
 import { generate_id } from "@/utils/Id.js";
-import { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
-import { SessionAssistantMessageState } from "@/session/messages/SessionAssistantMessageState.js";
-import { SessionActionMessageWriter } from "@/session/messages/SessionActionMessageWriter.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,
@@ -18,11 +18,11 @@ import {
 import type { JsonObject } from "@downcity/type";
 import type {
   ListSessionMessagesInput,
-  SessionActionMessage,
-  SessionAssistantInteractionPart,
-  SessionAssistantMessage,
-  SessionAssistantMessagePart,
-  SessionErrorMessage,
+  SessionAgentActionPart,
+  SessionAgentErrorPart,
+  SessionAgentInteractionPart,
+  SessionAgentMessage,
+  SessionAgentMessagePart,
   SessionMessage,
   SessionMessagePage,
   SessionUserMessage,
@@ -32,11 +32,7 @@ import type {
   SessionMutation,
   SessionMessageMutation as SessionMessageSnapshotMutation,
 } from "@downcity/type";
-import type {
-  SessionContextSnapshot,
-  SessionMessageStorageStats,
-  SessionSegmentSummary,
-} from "@/types/session/SessionSegment.js";
+import type { SessionMessageStorageStats } from "@/types/store/SessionStorage.js";
 import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
 import type {
   SessionInteractionCloseInput,
@@ -46,33 +42,34 @@ import type {
 import type { SessionActionEvent } from "@downcity/type";
 import { persist_user_prompt_file_parts } from "@executor/messages/SessionAttachmentMapper.js";
 import type {
-  AppendCompletedAssistantMessageInput,
-  AppendExternalSessionAssistantMessageInput,
+  AppendCompletedAgentMessageInput,
+  AppendExternalSessionAgentMessageInput,
   AppendExternalSessionUserMessageInput,
-  AppendSessionErrorMessageInput,
+  AppendSessionAgentErrorPartInput,
   AppendSessionPromptMessageInput,
   AppendSessionUserMessageInput,
-  OpenSessionActionMessageInput,
-  OpenSessionAssistantMessageInput,
+  OpenSessionAgentActionPartInput,
+  OpenSessionAgentMessageInput,
   SessionMessagesOptions,
 } from "@/types/session/SessionMessages.js";
-import type { SessionMessageStore } from "@/types/store/SessionDataStore.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
-export { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
-export { SessionActionMessageWriter } from "@/session/messages/SessionActionMessageWriter.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 写入服务。 */
 export class SessionMessages {
   readonly session_id: string;
-  private readonly store: SessionMessageStore;
+  private readonly store: SessionStorage;
   private readonly attachment_store: SessionAttachmentStore;
   private readonly publish: SessionMessagesOptions["publish"];
   private readonly messages_by_id = new Map<string, SessionMessage>();
   /** Assistant 草稿与 Interaction 的串行状态转换器。 */
-  private readonly assistant_state: SessionAssistantMessageState;
-  private initialized = false;
+  private readonly agent_state: SessionAgentMessageState;
+  /** 当前 Message 恢复事务；并发初始化共享同一个 Promise。 */
+  private initialize_promise: Promise<void> | null = null;
 
   constructor(options: SessionMessagesOptions) {
     this.session_id = String(options.session_id || "").trim();
@@ -80,35 +77,100 @@ export class SessionMessages {
     this.attachment_store = options.attachment_store;
     this.publish = options.publish;
     if (!this.session_id) throw new Error("SessionMessages requires session_id");
-    this.assistant_state = new SessionAssistantMessageState({
+    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),
-      accept_mutation: (mutation, message) =>
+      project_mutation: (mutation, message) =>
         this.accept_mutation(mutation, message),
     });
   }
 
   /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
   async initialize(): Promise<void> {
-    if (this.initialized) return;
-    await this.store.initialize();
-    for (const message of await this.store.list_messages()) {
-      this.messages_by_id.set(message.message_id, message);
+    if (!this.initialize_promise) {
+      this.initialize_promise = this.restore_messages();
     }
-    this.initialized = true;
-    const unfinished = [...this.messages_by_id.values()];
-    for (const message of unfinished) {
-      if (message.type === "assistant" && message.status === "streaming") {
-        await this.complete_assistant_message(message.message_id, "stopped");
-      }
-      if (message.type === "action" && message.status === "running") {
-        await this.update_action_message(message.message_id, "failed", {
-          description: message.description || "Action interrupted before completion.",
-        });
+    const initialize_promise = this.initialize_promise;
+    try {
+      await initialize_promise;
+    } catch (error) {
+      if (this.initialize_promise === initialize_promise) {
+        this.initialize_promise = null;
       }
+      throw error;
+    }
+  }
+
+  /** 只恢复非终态 Message，并由领域层统一收口进程中断状态。 */
+  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,
+        state: "done",
+        revision: message.revision + 1,
+        updated_at,
+        parts: [...message.parts.map((part) => {
+          if (part.type === "action" && part.state === "running") {
+            return {
+              ...part,
+              state: "failed" as const,
+              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"
+          ) {
+            return {
+              ...part,
+              state: "failed" as const,
+              error: "Tool interrupted before completion.",
+            };
+          }
+          if (
+            (part.type === "text" || part.type === "reasoning") &&
+            part.state === "streaming"
+          ) {
+            return { ...part, state: "done" as const };
+          }
+          return part;
+        }), {
+          part_id: `error:${generate_id()}`,
+          sequence: message.parts.reduce(
+            (sequence, part) => Math.max(sequence, part.sequence + 1),
+            1,
+          ),
+          type: "error",
+          scope: message.turn_id ? "turn" : "session",
+          code: "runtime_interrupted",
+          message: "Agent execution was interrupted before completion.",
+          recoverable: true,
+        }],
+      };
+      const changed_parts = resolve_changed_agent_parts(message, recovered);
+      await this.store.update_message({
+        message: recovered,
+        expected_revision: message.revision,
+        changed_parts,
+      });
+      this.accept_message(recovered, false);
     }
   }
 
@@ -117,14 +179,15 @@ export class SessionMessages {
     return this.messages_by_id.get(message_id);
   }
 
-  /** 追加普通 prompt 或 steering User Message。 */
+  /** 追加一条 canonical User Message。 */
   async append_user_message(
     input: AppendSessionUserMessageInput,
   ): Promise<SessionUserMessage> {
+    const message_id =
+      String(input.message_id || "").trim() ||
+      `user:${this.session_id}:${generate_id()}`;
     const message = await this.create_message((sequence, created_at) => ({
-      message_id:
-        String(input.message_id || "").trim() ||
-        `user:${this.session_id}:${generate_id()}`,
+      message_id,
       session_id: this.session_id,
       turn_id: input.turn_id,
       sequence,
@@ -132,21 +195,23 @@ export class SessionMessages {
       visibility: input.visibility || "visible",
       created_at,
       updated_at: created_at,
-      type: "user",
-      input_type: input.input_type,
-      parts: normalize_canonical_session_user_parts(input.parts),
+      role: "user",
+      parts: normalize_canonical_session_user_parts(input.parts).map((part) => ({
+        ...part,
+        part_id: `${message_id}:part:${String(part.sequence)}`,
+      })),
     }));
     return message as SessionUserMessage;
   }
 
   /** 创建可持续接收 chunk 的 Assistant Message。 */
-  async open_assistant_message(
-    input: OpenSessionAssistantMessageInput,
-  ): Promise<SessionAssistantMessageWriter> {
+  async open_agent_message(
+    input: OpenSessionAgentMessageInput,
+  ): Promise<SessionAgentMessageWriter> {
     const message = (await this.create_message((sequence, created_at) => ({
       message_id:
         String(input.message_id || "").trim() ||
-        `assistant:${this.session_id}:${generate_id()}`,
+        `agent:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       turn_id: input.turn_id,
       sequence,
@@ -154,33 +219,29 @@ export class SessionMessages {
       visibility: input.visibility || "visible",
       created_at,
       updated_at: created_at,
-      type: "assistant",
-      kind: input.kind || "normal",
-      status: "streaming",
+      role: "agent",
+      state: "streaming",
       parts: [],
-      ...(input.summary_through_message_id
-        ? { summary_through_message_id: input.summary_through_message_id }
-        : {}),
-    }), true)) as SessionAssistantMessage;
-    return new SessionAssistantMessageWriter(this, message.message_id);
+    }), true)) as SessionAgentMessage;
+    return new SessionAgentMessageWriter(this, message.message_id);
   }
 
   /** 直接写入一条已完成 Assistant Message。 */
-  async append_completed_assistant_message(
-    input: AppendCompletedAssistantMessageInput,
-  ): Promise<SessionAssistantMessage> {
+  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_assistant_message({
+    const writer = await this.open_agent_message({
       turn_id,
-      kind: input.kind || "normal",
       visibility: input.visibility || "visible",
-      ...(input.summary_through_message_id
-        ? { summary_through_message_id: input.summary_through_message_id }
-        : {}),
     });
     for (const part of input.parts) await writer.upsert_part(part);
     await writer.complete();
-    return this.get_message(writer.message_id) as SessionAssistantMessage;
+    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}`);
+    }
+    return message;
   }
 
   /** 把公开 Session API 的 User 输入转换为 canonical Message 并持久化。 */
@@ -195,22 +256,21 @@ export class SessionMessages {
     if (parts.length === 0) return false;
     await this.append_user_message({
       turn_id: `external:${this.session_id}:${Date.now()}`,
-      input_type: "prompt",
       parts,
     });
     return true;
   }
 
   /** 把公开 Session API 的 Assistant 输入转换为 canonical Message 并持久化。 */
-  async append_external_assistant_message(
-    input: AppendExternalSessionAssistantMessageInput,
+  async append_external_agent_message(
+    input: AppendExternalSessionAgentMessageInput,
   ): Promise<boolean> {
     const parts = input.parts || [{
       type: "text" as const,
       text: String(input.text || "").trim(),
     }];
     if (!has_assistant_result_content(parts)) return false;
-    const writer = await this.open_assistant_message({
+    const writer = await this.open_agent_message({
       turn_id: `external:${this.session_id}:${Date.now()}`,
     });
     await writer.append_result_parts(parts);
@@ -231,38 +291,27 @@ export class SessionMessages {
         );
     const canonical = await this.append_user_message({
       turn_id: input.turn_id,
-      input_type: input.input_type,
       parts: normalize_session_user_parts(ui_parts),
+      ...(input.message_id ? { message_id: input.message_id } : {}),
     });
     return canonical;
   }
 
-  /** 持久化 Executor 在本轮延迟产生的 User Message。 */
-  async append_deferred_user_messages(
-    deferred_messages?: SessionUserMessage[],
-  ): Promise<number> {
-    const messages = Array.isArray(deferred_messages)
-      ? deferred_messages
-      : [];
-    for (const message of messages) {
-      await this.append_user_message({
-        turn_id: message.turn_id || `deferred:${this.session_id}:${Date.now()}`,
-        input_type: "steer",
-        parts: structuredClone(message.parts),
-      });
-    }
-    return messages.length;
+  /** 读取指定 Turn 最近一条 canonical Agent Message。 */
+  async read_latest_agent_message(turn_id: string): Promise<SessionAgentMessage | null> {
+    return await this.store.read_latest_agent_message(turn_id);
   }
 
-  /** 按稳定 Action ID 创建或更新 canonical Action Message。 */
+  /** 按稳定 Action ID 创建或更新只包含 Action Part 的 Agent Message。 */
   async persist_action(
     event: SessionActionEvent,
     options?: { publish_mutation?: boolean },
   ): Promise<void> {
     const publish_mutation = options?.publish_mutation !== false;
-    const existing = this.get_message(event.action_id);
+    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_message({
+      const writer = await this.open_action_part({
         message_id: event.action_id,
         turn_id: event.turn_id,
         action_type: event.action_type,
@@ -276,22 +325,23 @@ export class SessionMessages {
       }
       return;
     }
-    if (existing.type === "action" && event.status !== "running") {
-      await this.update_action_message(event.action_id, event.status, {
+    if (existing.role === "agent" && event.status !== "running") {
+      await this.update_action_part(event.action_id, event.status, {
         title: event.title,
         description: event.description,
       }, { publish_mutation });
     }
   }
 
-  /** 创建 running Action Message。 */
-  async open_action_message(
-    input: OpenSessionActionMessageInput,
-  ): Promise<SessionActionMessageWriter> {
+  /** 创建只包含 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:
-        String(input.message_id || "").trim() ||
-        `action:${this.session_id}:${generate_id()}`,
+      message_id,
       session_id: this.session_id,
       ...(input.turn_id ? { turn_id: input.turn_id } : {}),
       sequence,
@@ -299,14 +349,21 @@ export class SessionMessages {
       visibility: "visible",
       created_at,
       updated_at: created_at,
-      type: "action",
-      action_type: input.action_type,
-      status: "running",
-      title: input.title,
-      ...(input.description ? { description: input.description } : {}),
-      ...(input.data ? { data: structuredClone(input.data) } : {}),
-    }), false, input.publish_mutation !== false)) as SessionActionMessage;
-    return new SessionActionMessageWriter(
+      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,
@@ -314,37 +371,110 @@ export class SessionMessages {
   }
 
   /** 更新 Action 状态，同时保持 message_id 与 sequence 不变。 */
-  async update_action_message(
+  async update_action_part(
     message_id: string,
     status: "running" | "completed" | "failed",
     changes?: { title?: string; description?: string; data?: JsonObject },
     options?: { publish_mutation?: boolean },
-  ): Promise<SessionActionMessage> {
-    const message = await this.store.append_message((state) => {
-      const current = require_message(state.messages, message_id, "action");
-      const created_at = Date.now();
-      return {
-        ...current,
-        status,
-        ...(changes?.title ? { title: changes.title } : {}),
-        ...(changes?.description !== undefined
-          ? { description: changes.description }
-          : {}),
-        ...(changes?.data ? { data: structuredClone(changes.data) } : {}),
-        revision: current.revision + 1,
-        updated_at: created_at,
-      } satisfies SessionActionMessage;
+  ): 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 action = current_message.parts.find(
+        (part): part is SessionAgentActionPart => part.type === "action",
+      );
+    if (!action) throw new Error(`Session Action Part not found: ${message_id}`);
+    const next_action: SessionAgentActionPart = {
+      ...action,
+      state: status,
+      ...(changes?.title ? { title: changes.title } : {}),
+      ...(changes?.description !== undefined
+        ? { description: changes.description }
+        : {}),
+      ...(changes?.data ? { data: structuredClone(changes.data) } : {}),
+    };
+    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),
+      revision: current_message.revision + 1,
+      updated_at: Date.now(),
+    };
+    await this.store.update_message({
+      message,
+      expected_revision: current_message.revision,
+      changed_parts: [next_action],
     });
     this.accept_message(message, options?.publish_mutation !== false);
-    return message as SessionActionMessage;
-  }
+    return message as SessionAgentMessage;
+  }
+
+  /**
+   * 将 Error Part 追加到当前 Turn 最后一个 Agent Message。
+   *
+   * 同一错误码已经存在时保持幂等；只有当前 Turn 从未产生 Agent Message 时，才创建
+   * 一个仅含 Error 的失败 Message。这样错误与已经产生的 Text、Tool 和 Diff 始终
+   * 共享同一 Message，并由 Part sequence 表达真实顺序。
+   */
+  async append_error_part(
+    input: AppendSessionAgentErrorPartInput,
+  ): Promise<SessionAgentMessage> {
+    await this.ensure_initialized();
+    const target = await this.store.read_latest_agent_message(input.turn_id);
+    const existing_error = target?.parts.find(
+      (part): part is SessionAgentErrorPart =>
+        part.type === "error" && part.code === input.code,
+    );
+    if (target && existing_error) {
+      return target;
+    }
+
+    const error_part: SessionAgentErrorPart = {
+      part_id: `error:${generate_id()}`,
+      sequence: target
+        ? target.parts.reduce(
+            (sequence, part) => Math.max(sequence, part.sequence + 1),
+            1,
+          )
+        : 1,
+      type: "error",
+      scope: input.scope,
+      code: input.code,
+      message: input.message,
+      recoverable: input.recoverable,
+    };
+
+    if (target?.state === "streaming") {
+      this.remember_message(target);
+      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") {
+        throw new Error(`Agent Message not found after Error Part commit: ${target.message_id}`);
+      }
+      return updated;
+    }
+
+    if (target) {
+      const message: SessionAgentMessage = {
+        ...target,
+        revision: target.revision + 1,
+        updated_at: Date.now(),
+        parts: [...target.parts, error_part].sort(
+          (left, right) => left.sequence - right.sequence,
+        ),
+      };
+      await this.store.update_message({
+        message,
+        expected_revision: target.revision,
+        changed_parts: [error_part],
+      });
+      this.accept_message(message);
+      return message as SessionAgentMessage;
+    }
 
-  /** 创建用户可见 Error Message。 */
-  async append_error_message(
-    input: AppendSessionErrorMessageInput,
-  ): Promise<SessionErrorMessage> {
     return (await this.create_message((sequence, created_at) => ({
-      message_id: `error:${this.session_id}:${generate_id()}`,
+      message_id: `agent:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       ...(input.turn_id ? { turn_id: input.turn_id } : {}),
       sequence,
@@ -352,94 +482,57 @@ export class SessionMessages {
       visibility: "visible",
       created_at,
       updated_at: created_at,
-      type: "error",
-      scope: input.scope,
-      code: input.code,
-      message: input.message,
-      recoverable: input.recoverable,
-    }))) as SessionErrorMessage;
+      role: "agent",
+      state: "done",
+      parts: [error_part],
+    }))) as SessionAgentMessage;
   }
 
-  /** 读取 Active 或指定边界之前最近的完整 Segment。 */
+  /** 按 Message sequence 返回一页完整 Message 聚合。 */
   async list_messages(
     input?: ListSessionMessagesInput,
   ): Promise<SessionMessagePage> {
     await this.ensure_initialized();
-    const requests_segment = input?.before_sequence !== undefined;
     const before_sequence = input?.before_sequence;
     if (
-      requests_segment &&
+      before_sequence !== undefined &&
       (!Number.isInteger(before_sequence) || Number(before_sequence) <= 0)
     ) {
       throw new Error("before_sequence must be a positive integer");
     }
-    const segment = requests_segment
-      ? await this.store.read_segment_before(Number(before_sequence))
-      : null;
-    const source = requests_segment ? "segment" as const : "active" as const;
-    const messages = requests_segment
-      ? segment?.messages || []
-      : [...this.messages_by_id.values()].sort(compare_message_sequence);
+    const limit = Math.min(Math.max(input?.limit ?? 50, 1), 200);
+    const page = await this.store.list_message_page({
+      ...(before_sequence !== undefined ? { before_sequence } : {}),
+      limit: limit + 1,
+      include_internal: input?.include_internal === true,
+    });
+    const has_more = page.length > limit;
+    const messages = has_more ? page.slice(1) : page;
     const start_sequence = messages[0]?.sequence;
     const end_sequence = messages.at(-1)?.sequence;
-    const history_boundary = source === "segment"
-      ? segment?.range.start_sequence
-      : await this.store.active_before_sequence(messages);
-    const has_more = history_boundary !== undefined &&
-      await this.store.has_segment_before(history_boundary);
-    const stats = await this.store.stats();
-    const items = messages
-      .filter((message) => input?.include_internal === true || message.visibility === "visible")
-      .map((message) => structuredClone(message));
+    const stats = await this.store.message_stats();
     return {
-      items,
+      items: messages.map((message) => structuredClone(message)),
       total: stats.message_count,
-      source,
       ...(start_sequence !== undefined ? { start_sequence } : {}),
       ...(end_sequence !== undefined ? { end_sequence } : {}),
-      ...(has_more && history_boundary !== undefined
-        ? { next_before_sequence: history_boundary }
+      ...(has_more && start_sequence !== undefined
+        ? { next_before_sequence: start_sequence }
         : {}),
       has_more,
     };
   }
 
-  /** 读取最新累计 Summary 与全部 Active Message，供模型上下文使用。 */
-  async context_snapshot(): Promise<SessionContextSnapshot> {
-    await this.ensure_initialized();
-    return {
-      summary: await this.store.read_latest_summary(),
-      messages: [...this.messages_by_id.values()]
-        .sort(compare_message_sequence)
-        .map((message) => structuredClone(message)),
-    };
-  }
-
   /** 读取全部真实历史，供 Fork 等明确的全量复制操作使用。 */
   async list_history_messages(): Promise<SessionMessage[]> {
     await this.ensure_initialized();
-    return await this.store.list_history_messages();
+    return await this.store.list_messages();
   }
 
   /** 读取当前 Session 的存储统计。 */
   async storage_stats(): Promise<SessionMessageStorageStats> {
     await this.ensure_initialized();
-    return await this.store.stats();
-  }
-
-  /** 把 Active 前缀和累计 Summary 提交为不可变 Segment。 */
-  async compact_active(input: {
-    /** 移入 Segment 的最后一条真实 Message sequence。 */
-    through_sequence: number;
-    /** 写入 Segment footer 的累计 Summary。 */
-    summary: SessionSegmentSummary;
-  }): Promise<void> {
-    await this.ensure_initialized();
-    const result = await this.store.compact_active(input);
-    this.messages_by_id.clear();
-    for (const message of result.active_messages) {
-      this.messages_by_id.set(message.message_id, structuredClone(message));
-    }
+    return await this.store.message_stats();
   }
 
   /** 向当前 Session 导入 fork 来源 Message，并重新分配全部身份和顺序。 */
@@ -453,7 +546,7 @@ export class SessionMessages {
       const message_id = resolve_import_id(
         message_ids,
         source.message_id,
-        source.type,
+        source.role,
       );
       await this.create_message((sequence, created_at) => ({
         ...structuredClone(source),
@@ -473,54 +566,73 @@ export class SessionMessages {
     }
   }
 
-  /** @internal 写入 Assistant 原始文本 delta。 */
-  async append_assistant_delta(
+  /** @internal 只向运行投影追加 Agent 文本 delta。 */
+  project_agent_delta(
     message_id: string,
     part_id: string,
     type: "text" | "reasoning",
     delta: string,
-  ): Promise<void> {
-    await this.assistant_state.append_delta(message_id, part_id, type, delta);
+  ): void {
+    this.agent_state.project_delta(message_id, part_id, type, delta);
   }
 
-  /** @internal 写入 Assistant Tool 输入原始 delta。 */
-  async append_assistant_tool_input_delta(
+  /** @internal 只向运行投影追加 Agent Tool 输入 delta。 */
+  project_agent_tool_input_delta(
     message_id: string,
     part_id: string,
     tool_call_id: string,
     delta: string,
-  ): Promise<void> {
-    await this.assistant_state.append_tool_input_delta(
+  ): void {
+    this.agent_state.project_delta(
       message_id,
       part_id,
-      tool_call_id,
+      "tool_input",
       delta,
+      tool_call_id,
     );
   }
 
-  /** @internal 写入 Assistant 完整 part。 */
-  async update_assistant_part(
+  /** @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,
-    part: SessionAssistantMessagePart,
+    parts: readonly SessionAgentMessagePart[],
   ): Promise<void> {
-    await this.assistant_state.update_part(message_id, part);
+    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_assistant_step(
+  async commit_agent_step(
     message_id: string,
-    parts: SessionAssistantMessagePart[],
+    parts: SessionAgentMessagePart[],
   ): Promise<void> {
-    await this.assistant_state.commit_step(message_id, parts);
+    await this.agent_state.commit_step(message_id, parts);
   }
 
   /** @internal 收口 Assistant Message。 */
-  async complete_assistant_message(
+  async complete_agent_message(
     message_id: string,
     status: "completed" | "stopped" | "failed",
     error?: string,
   ): Promise<void> {
-    await this.assistant_state.complete(message_id, status, error);
+    await this.agent_state.complete(message_id, status, error);
   }
 
   private async create_message(
@@ -529,47 +641,40 @@ export class SessionMessages {
     publish_mutation = true,
   ): Promise<SessionMessage> {
     await this.ensure_initialized();
-    if (draft) {
-      const message = await this.store.create_assistant_message((state) => {
-        const candidate = factory(state.message_sequence, Date.now());
-        if (candidate.type !== "assistant" || candidate.status !== "streaming") {
-          throw new Error("Draft Message must be a streaming Assistant");
-        }
-        return candidate;
-      });
-      this.accept_message(message, publish_mutation);
-      return message;
-    }
-    const message = await this.store.append_message((state) =>
-      factory(state.message_sequence, Date.now()),
-    );
+    const message = await this.store.create_message((state) => {
+      const candidate = factory(state.message_sequence, Date.now());
+      if (draft && (candidate.role !== "agent" || candidate.state !== "streaming")) {
+        throw new Error("Draft Message must be a streaming Agent Message");
+      }
+      return candidate;
+    });
     this.accept_message(message, publish_mutation);
     return message;
   }
 
   /** 读取当前流式 Assistant 中的指定 Tool Part。 */
   find_streaming_tool(tool_call_id: string): SessionStreamingToolLocation | undefined {
-    return this.assistant_state.find_streaming_tool(tool_call_id);
+    return this.agent_state.find_streaming_tool(tool_call_id);
   }
 
   /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
-  list_pending_interactions(): SessionAssistantInteractionPart[] {
-    return this.assistant_state.list_pending_interactions();
+  list_pending_interactions(): SessionAgentInteractionPart[] {
+    return this.agent_state.list_pending_interactions();
   }
 
   /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
   async request_interaction(
     request: SessionInteractionRequest,
-  ): Promise<SessionAssistantInteractionPart> {
-    return await this.assistant_state.request_interaction(request);
+  ): Promise<SessionAgentInteractionPart> {
+    return await this.agent_state.request_interaction(request);
   }
 
   /** 原子保存用户响应，并按 Interaction 结果恢复或终止关联 Tool。 */
   async resolve_interaction(
     interaction_id: string,
     response: SessionInteractionResponse,
-  ): Promise<SessionAssistantInteractionPart> {
-    return await this.assistant_state.resolve_interaction(
+  ): Promise<SessionAgentInteractionPart> {
+    return await this.agent_state.resolve_interaction(
       interaction_id,
       response,
     );
@@ -579,8 +684,8 @@ export class SessionMessages {
   async close_interaction(
     interaction_id: string,
     input: SessionInteractionCloseInput,
-  ): Promise<SessionAssistantInteractionPart> {
-    return await this.assistant_state.close_interaction(interaction_id, input);
+  ): Promise<SessionAgentInteractionPart> {
+    return await this.agent_state.close_interaction(interaction_id, input);
   }
 
   private build_message_mutation(
@@ -589,7 +694,7 @@ export class SessionMessages {
     return {
       mutation_id: generate_id(),
       variant: "message",
-      type: message.type,
+      role: message.role,
       message_id: message.message_id,
       sequence: message.sequence,
       revision: message.revision,
@@ -602,33 +707,41 @@ export class SessionMessages {
 
   private accept_message(message: SessionMessage, publish_mutation = true): void {
     if (!publish_mutation) {
-      this.messages_by_id.set(message.message_id, structuredClone(message));
+      this.remember_message(message);
       return;
     }
     this.accept_mutation(this.build_message_mutation(message), message);
   }
 
   private accept_mutation(mutation: SessionMutation, message: SessionMessage): void {
-    this.messages_by_id.set(message.message_id, structuredClone(message));
+    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> {
-    if (!this.initialized) await this.initialize();
+    await this.initialize();
   }
 
 }
 
-function require_message<TType extends SessionMessage["type"]>(
+function require_message<TRole extends SessionMessage["role"]>(
   messages: SessionMessage[],
   message_id: string,
-  type: TType,
-): Extract<SessionMessage, { type: TType }> {
+  role: TRole,
+): Extract<SessionMessage, { role: TRole }> {
   const message = messages.find((item) => item.message_id === message_id);
-  if (!message || message.type !== type) {
-    throw new Error(`Session ${type} Message not found: ${message_id}`);
+  if (!message || message.role !== role) {
+    throw new Error(`Session ${role} Message not found: ${message_id}`);
   }
-  return message as Extract<SessionMessage, { type: TType }>;
+  return message as Extract<SessionMessage, { role: TRole }>;
 }
 
 function resolve_import_id(map: Map<string, string>, source_id: string, prefix: string): string {
@@ -640,6 +753,14 @@ function resolve_import_id(map: Map<string, string>, source_id: string, prefix:
 }
 
 /** 按真实 Message sequence 升序排序。 */
-function compare_message_sequence(left: SessionMessage, right: SessionMessage): number {
-  return left.sequence - right.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),
+  );
 }