@downcity/agent 1.1.408 → 1.1.437

package/src/session/SessionMessages.ts

@@ -6,72 +6,70 @@
  * 从最新快照严格递增。
  */
 
-import type {
-  SessionAssistantResultPart,
-  SessionPromptPart,
-} from "@/types/session/SessionContent.js";
 import { generate_id } from "@/utils/Id.js";
-import { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
-import { SessionMessageInteractionWriter } from "@/session/messages/SessionMessageInteractionWriter.js";
-import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
-import type { JsonObject } from "@/types/common/Json.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,
-  SessionActionMessage,
-  SessionAssistantInteractionPart,
-  SessionAssistantMessage,
-  SessionAssistantMessagePart,
-  SessionAssistantToolPart,
-  SessionErrorMessage,
+  SessionAgentActionPart,
+  SessionAgentErrorPart,
+  SessionAgentInteractionPart,
+  SessionAgentMessage,
+  SessionAgentMessagePart,
   SessionMessage,
   SessionMessagePage,
   SessionUserMessage,
   SessionUserMessagePart,
-} from "@/types/session/SessionMessage.js";
+} from "@downcity/type";
 import type {
   SessionMutation,
   SessionMessageMutation as SessionMessageSnapshotMutation,
-} from "@/types/session/SessionMutation.js";
-import type {
-  SessionContextSnapshot,
-  SessionMessageStorageStats,
-  SessionSegmentSummary,
-} from "@/types/session/SessionSegment.js";
+} from "@downcity/type";
+import type { SessionMessageStorageStats } from "@/types/store/SessionStorage.js";
 import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
 import type {
+  SessionInteractionCloseInput,
   SessionInteractionRequest,
   SessionInteractionResponse,
-} from "@/types/session/SessionInteraction.js";
-import type { SessionActionEvent } from "@/types/session/SessionAction.js";
+} from "@downcity/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 { 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 Message 隔离的完整写事务链。 */
-  private readonly assistant_write_chains = new Map<string, Promise<void>>();
-  /** Assistant Message 内 Interaction Part 的原子状态写入器。 */
-  private readonly interaction_writer: SessionMessageInteractionWriter;
-  private initialized = false;
+  /** Assistant 草稿与 Interaction 的串行状态转换器。 */
+  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();
@@ -79,34 +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.interaction_writer = new SessionMessageInteractionWriter({
+    this.agent_state = new SessionAgentMessageState({
+      session_id: this.session_id,
+      store: this.store,
       list_messages: () => this.messages_by_id.values(),
-      find_streaming_tool: (tool_call_id) => this.find_streaming_tool(tool_call_id),
-      enqueue_assistant_write: (message_id, operation) =>
-        this.enqueue_assistant_write(message_id, operation),
-      commit_assistant_snapshot: (current, parts) =>
-        this.commit_assistant_snapshot(current, parts),
+      accept_message: (message, publish_mutation) =>
+        this.accept_message(message, publish_mutation),
+      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);
     }
   }
 
@@ -115,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,
@@ -130,21 +195,23 @@ export class SessionMessages {
       visibility: input.visibility || "visible",
       created_at,
       updated_at: created_at,
-      type: "user",
-      input_type: input.input_type,
-      parts: structuredClone(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,
@@ -152,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 并持久化。 */
@@ -193,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);
@@ -229,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,
@@ -274,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,
@@ -297,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,
@@ -312,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 Message。 */
-  async append_error_message(
-    input: AppendSessionErrorMessageInput,
-  ): Promise<SessionErrorMessage> {
+  /**
+   * 将 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;
+    }
+
     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,
@@ -350,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，并重新分配全部身份和顺序。 */
@@ -451,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),
@@ -471,261 +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> {
-    if (!delta) return;
-    await this.enqueue_assistant_write(message_id, async () => {
-      await this.append_assistant_delta_serialized(message_id, part_id, type, delta);
-    });
+  ): void {
+    this.agent_state.project_delta(message_id, part_id, type, delta);
   }
 
-  /** 在 Assistant 写队列内追加文本 delta。 */
-  private async append_assistant_delta_serialized(
+  /** @internal 只向运行投影追加 Agent Tool 输入 delta。 */
+  project_agent_tool_input_delta(
     message_id: string,
     part_id: string,
-    type: "text" | "reasoning",
+    tool_call_id: string,
     delta: string,
-  ): Promise<void> {
-    const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
-    require_streaming_assistant(current);
-    const part = current.parts.find((item) => item.part_id === part_id);
-    if (!part || (part.type !== "text" && part.type !== "reasoning")) {
-      throw new Error(`Delta target Part does not exist: ${part_id}`);
-    }
-    if (part.type !== type) throw new Error(`Delta type changed for Part: ${part_id}`);
-    const created_at = Date.now();
-    const message: SessionAssistantMessage = {
-      ...current,
-      revision: current.revision + 1,
-      updated_at: created_at,
-      parts: current.parts.map((item) =>
-        item.part_id === part_id && (item.type === "text" || item.type === "reasoning")
-          ? { ...item, text: item.text + delta }
-          : item,
-      ),
-    };
-    await this.store.write_assistant_message(message);
-    this.accept_mutation({
-      mutation_id: generate_id(),
-      variant: "delta",
-      type,
+  ): void {
+    this.agent_state.project_delta(
       message_id,
-      revision: message.revision,
-      session_id: this.session_id,
-      turn_id: message.turn_id,
-      created_at,
       part_id,
+      "tool_input",
       delta,
-    }, message);
+      tool_call_id,
+    );
   }
 
-  /** @internal 写入 Assistant Tool 输入原始 delta。 */
-  async append_assistant_tool_input_delta(
+  /** @internal 只向运行投影写入 Agent 完整 Part。 */
+  project_agent_part(
     message_id: string,
-    part_id: string,
-    tool_call_id: string,
-    delta: string,
-  ): Promise<void> {
-    if (!delta) return;
-    await this.enqueue_assistant_write(message_id, async () => {
-      const current = require_message(
-        [...this.messages_by_id.values()],
-        message_id,
-        "assistant",
-      );
-      require_streaming_assistant(current);
-      const part = current.parts.find((item) => item.part_id === part_id);
-      if (!part || part.type !== "tool") {
-        throw new Error(`Tool input Delta target Part does not exist: ${part_id}`);
-      }
-      if (part.tool_call_id !== tool_call_id) {
-        throw new Error(`Tool input Delta tool_call_id changed for Part: ${part_id}`);
-      }
-      if (part.state !== "input-streaming") {
-        throw new Error(`Tool input Delta cannot update ${part.state} Part: ${part_id}`);
-      }
-      const created_at = Date.now();
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        updated_at: created_at,
-        parts: current.parts.map((item) =>
-          item.part_id === part_id && item.type === "tool"
-            ? { ...item, input_text: `${item.input_text || ""}${delta}` }
-            : item,
-        ),
-      };
-      await this.store.write_assistant_message(message);
-      this.accept_mutation({
-        mutation_id: generate_id(),
-        variant: "delta",
-        type: "tool_input",
-        message_id,
-        revision: message.revision,
-        session_id: this.session_id,
-        turn_id: message.turn_id,
-        created_at,
-        part_id,
-        tool_call_id,
-        delta,
-      }, message);
-    });
+    part: SessionAgentMessagePart,
+  ): void {
+    this.agent_state.project_part(message_id, part);
   }
 
-  /** @internal 写入 Assistant 完整 part。 */
-  async update_assistant_part(
-    message_id: string,
-    part: SessionAssistantMessagePart,
-  ): Promise<void> {
-    await this.enqueue_assistant_write(message_id, async () => {
-      await this.update_assistant_part_serialized(message_id, part);
-    });
+  /** @internal 原子提交当前运行投影。 */
+  async checkpoint_agent_message(message_id: string): Promise<void> {
+    await this.agent_state.checkpoint(message_id);
   }
 
-  /** 在 Assistant 写队列内提交完整 Part 快照。 */
-  private async update_assistant_part_serialized(
+  /** @internal 原子提交一组非流式 Agent Parts。 */
+  async commit_agent_parts(
     message_id: string,
-    part: SessionAssistantMessagePart,
+    parts: readonly SessionAgentMessagePart[],
   ): Promise<void> {
-    const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
-    require_streaming_assistant(current);
-    const existing = current.parts.find((item) => item.part_id === part.part_id);
-    if (existing && existing.sequence !== part.sequence) {
-      throw new Error(`Assistant Part sequence changed: ${part.part_id}`);
-    }
-    const created_at = Date.now();
-    const next_part = structuredClone(part);
-    const message: SessionAssistantMessage = {
-      ...current,
-      revision: current.revision + 1,
-      updated_at: created_at,
-      parts: (existing
-        ? current.parts.map((item) => item.part_id === part.part_id ? next_part : item)
-        : [...current.parts, next_part]
-      ).sort((left, right) => left.sequence - right.sequence),
-    };
-    await this.store.write_assistant_message(message);
-    this.accept_mutation({
-      mutation_id: generate_id(),
-      variant: "part",
-      type: next_part.type,
-      message_id,
-      revision: message.revision,
-      session_id: this.session_id,
-      turn_id: message.turn_id,
-      created_at,
-      part_id: next_part.part_id,
-      part: next_part,
-    } as SessionMutation, message);
+    await this.agent_state.commit_parts(message_id, parts);
   }
 
-  /** @internal 原子提交当前 Assistant step 的 metadata 快照。 */
-  async commit_assistant_step(
-    message_id: string,
-    parts: SessionAssistantMessagePart[],
-  ): Promise<void> {
-    await this.enqueue_assistant_write(message_id, async () => {
-      const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
-      require_streaming_assistant(current);
-      if (
-        parts.length !== current.parts.length ||
-        parts.some((part, index) =>
-          part.part_id !== current.parts[index]?.part_id ||
-          part.sequence !== current.parts[index]?.sequence
-        )
-      ) {
-        throw new Error(
-          `Assistant step changed canonical Part identity: ${message_id}`,
-        );
-      }
-      const created_at = Date.now();
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        updated_at: created_at,
-        parts: structuredClone(parts),
-      };
-      await this.store.write_assistant_message(message);
-      this.accept_message(message);
-    });
+  /** @internal 丢弃未提交的当前 Step 投影。 */
+  async rollback_agent_projection(message_id: string): Promise<void> {
+    await this.agent_state.rollback_projection(message_id);
   }
 
-  /** @internal 收口 Assistant Message。 */
-  async complete_assistant_message(
+  /** @internal 原子提交当前 Assistant step 的 metadata 快照。 */
+  async commit_agent_step(
     message_id: string,
-    status: "completed" | "stopped" | "failed",
-    error?: string,
+    parts: SessionAgentMessagePart[],
   ): Promise<void> {
-    await this.enqueue_assistant_write(message_id, async () => {
-      await this.complete_assistant_message_serialized(message_id, status, error);
-    });
+    await this.agent_state.commit_step(message_id, parts);
   }
 
-  /** 在 Assistant 写队列内关闭草稿并写入 Active。 */
-  private async complete_assistant_message_serialized(
+  /** @internal 收口 Assistant Message。 */
+  async complete_agent_message(
     message_id: string,
     status: "completed" | "stopped" | "failed",
     error?: string,
   ): Promise<void> {
-    const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
-    require_streaming_assistant(current);
-    const created_at = Date.now();
-    const interrupted_interactions = status === "stopped"
-      ? current.parts.filter(
-          (part): part is SessionAssistantInteractionPart =>
-            part.type === "interaction" && part.status === "pending",
-        )
-      : [];
-    const interrupted_tool_ids = new Set(
-      interrupted_interactions.flatMap((part) =>
-        part.request.source.tool_call_id
-          ? [part.request.source.tool_call_id]
-          : [],
-      ),
-    );
-    const message: SessionAssistantMessage = {
-      ...current,
-      revision: current.revision + 1,
-      status,
-      updated_at: created_at,
-      parts: current.parts.map((part) => {
-        if (part.type === "text" || part.type === "reasoning") {
-          return { ...part, state: "done" as const };
-        }
-        if (part.type === "interaction" && part.status === "pending") {
-          return {
-            ...part,
-            status: "cancelled" as const,
-            cancel_reason: "runtime_interrupted" as const,
-            resolved_at: created_at,
-          };
-        }
-        if (
-          part.type === "tool" &&
-          part.state !== "completed" &&
-          part.state !== "failed"
-        ) {
-          return {
-            ...part,
-            state: "failed" as const,
-            error:
-              status === "stopped" &&
-              part.state === "waiting-user" &&
-              interrupted_tool_ids.has(part.tool_call_id)
-                ? "Interaction cancelled"
-                : error || "Tool did not complete before Assistant Message closed",
-          };
-        }
-        return part;
-      }),
-    };
-    await this.store.finalize_assistant_message(message);
-    this.accept_message(message);
+    await this.agent_state.complete(message_id, status, error);
   }
 
   private async create_message(
@@ -734,132 +641,51 @@ 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 {
-    for (const message of this.messages_by_id.values()) {
-      if (message.type !== "assistant" || message.status !== "streaming") continue;
-      const part = message.parts.find(
-        (item): item is SessionAssistantToolPart =>
-          item.type === "tool" && item.tool_call_id === tool_call_id,
-      );
-      if (part) return { message_id: message.message_id, part };
-    }
-    return undefined;
+    return this.agent_state.find_streaming_tool(tool_call_id);
   }
 
   /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
-  list_pending_interactions(): SessionAssistantInteractionPart[] {
-    return this.interaction_writer.list_pending();
+  list_pending_interactions(): SessionAgentInteractionPart[] {
+    return this.agent_state.list_pending_interactions();
   }
 
   /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
   async request_interaction(
     request: SessionInteractionRequest,
-  ): Promise<SessionAssistantInteractionPart> {
-    return this.interaction_writer.request(request);
+  ): Promise<SessionAgentInteractionPart> {
+    return await this.agent_state.request_interaction(request);
   }
 
   /** 原子保存用户响应，并按 Interaction 结果恢复或终止关联 Tool。 */
   async resolve_interaction(
     interaction_id: string,
     response: SessionInteractionResponse,
-  ): Promise<SessionAssistantInteractionPart> {
-    return this.interaction_writer.resolve(interaction_id, response);
+  ): Promise<SessionAgentInteractionPart> {
+    return await this.agent_state.resolve_interaction(
+      interaction_id,
+      response,
+    );
   }
 
   /** 原子结束未响应 Interaction，并把关联 Tool 标记为失败。 */
   async close_interaction(
     interaction_id: string,
-    input:
-      | { status: "expired" }
-      | {
-          status: "cancelled";
-          reason: "turn_stopped" | "session_disposed" | "runtime_interrupted";
-        },
-  ): Promise<SessionAssistantInteractionPart> {
-    return this.interaction_writer.close(interaction_id, input);
-  }
-
-  /**
-   * 串行执行同一 Assistant Message 的完整写事务。
-   *
-   * 失败事务不会阻塞后续写入；链尾仅用于排序，真实错误仍返回给调用方。
-   */
-  private async enqueue_assistant_write<T>(
-    message_id: string,
-    operation: () => Promise<T>,
-  ): Promise<T> {
-    const previous = this.assistant_write_chains.get(message_id) || Promise.resolve();
-    const result = previous.then(operation, operation);
-    const chain = result.then(() => undefined, () => undefined);
-    this.assistant_write_chains.set(message_id, chain);
-    try {
-      return await result;
-    } finally {
-      if (this.assistant_write_chains.get(message_id) === chain) {
-        this.assistant_write_chains.delete(message_id);
-      }
-    }
-  }
-
-  /** 原子提交包含多个 Part 状态变化的 Assistant 完整快照。 */
-  private async commit_assistant_snapshot(
-    current: SessionAssistantMessage,
-    parts: SessionAssistantMessagePart[],
-  ): Promise<void> {
-    const created_at = Date.now();
-    const message: SessionAssistantMessage = {
-      ...current,
-      revision: current.revision + 1,
-      updated_at: created_at,
-      parts: structuredClone(parts).sort(
-        (left, right) => left.sequence - right.sequence,
-      ),
-    };
-    await this.store.write_assistant_message(message);
-    const current_by_id = new Map(
-      current.parts.map((part) => [part.part_id, part]),
-    );
-    const changed_parts = message.parts.filter((part) => {
-      const previous = current_by_id.get(part.part_id);
-      return !previous || JSON.stringify(previous) !== JSON.stringify(part);
-    });
-    if (changed_parts.length === 0) {
-      this.accept_message(message);
-      return;
-    }
-    for (const part of changed_parts) {
-      this.accept_mutation({
-        mutation_id: generate_id(),
-        variant: "part",
-        type: part.type,
-        message_id: message.message_id,
-        revision: message.revision,
-        session_id: this.session_id,
-        turn_id: message.turn_id,
-        created_at,
-        part_id: part.part_id,
-        part: structuredClone(part),
-      } as SessionMutation, message);
-    }
+    input: SessionInteractionCloseInput,
+  ): Promise<SessionAgentInteractionPart> {
+    return await this.agent_state.close_interaction(interaction_id, input);
   }
 
   private build_message_mutation(
@@ -868,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,
@@ -881,132 +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);
   }
 
-  private async ensure_initialized(): Promise<void> {
-    if (!this.initialized) await this.initialize();
-  }
-
-}
-/** 单个 Action Message 的生命周期 writer。 */
-export class SessionActionMessageWriter {
-  readonly message_id: string;
-  private readonly messages: SessionMessages;
-  private readonly publish_mutation: boolean;
-  private closed = false;
-
-  constructor(
-    messages: SessionMessages,
-    message_id: string,
-    publish_mutation = true,
-  ) {
-    this.messages = messages;
-    this.message_id = message_id;
-    this.publish_mutation = 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));
+    }
   }
 
-  /** 把 Action 更新为 completed。 */
-  async complete(input?: { title?: string; description?: string; data?: JsonObject }): Promise<void> {
-    if (this.closed) return;
-    await this.messages.update_action_message(
-      this.message_id,
-      "completed",
-      input,
-      { publish_mutation: this.publish_mutation },
-    );
-    this.closed = true;
+  private async ensure_initialized(): Promise<void> {
+    await this.initialize();
   }
 
-  /** 把 Action 更新为 failed。 */
-  async fail(error: unknown): Promise<void> {
-    if (this.closed) return;
-    await this.messages.update_action_message(
-      this.message_id,
-      "failed",
-      {
-        description: error instanceof Error ? error.message : String(error),
-      },
-      { publish_mutation: this.publish_mutation },
-    );
-    this.closed = true;
-  }
 }
 
-/** 把 Downcity Session User parts 归一为 canonical User parts。 */
-export function normalize_session_user_parts(
-  parts: SessionPromptPart[] | null | undefined,
-): SessionUserMessagePart[] {
-  if (!Array.isArray(parts)) return [];
-  return parts.flatMap<SessionUserMessagePart>((part, index) => {
-    if (part.type === "text") {
-      return [{
-        part_id: `user-text:${index + 1}`,
-        type: "text",
-        text: part.text,
-        state: "done",
-      }];
-    }
-    if (part.type === "file") {
-      return [{
-        part_id: `user-file:${index + 1}`,
-        type: "file",
-        url: part.url,
-        media_type: part.media_type,
-        ...(part.filename ? { filename: part.filename } : {}),
-      }];
-    }
-    return [{
-      part_id: `user-data:${index + 1}`,
-      type: "data",
-      data_type: part.data_type,
-      data: to_session_json_value(part.data),
-      ...(part.data_id ? { data_id: part.data_id } : {}),
-    }];
-  });
-}
-
-/** 判断 Assistant 结果中是否包含可持久化内容。 */
-function has_assistant_result_content(
-  parts: readonly SessionAssistantResultPart[],
-): boolean {
-  return parts.some((part) => {
-    if (part.type === "text") return Boolean(part.text.trim());
-    if (part.type === "file") return Boolean(part.media_type.trim() && part.url.trim());
-    return Boolean(part.data_type.trim());
-  });
-}
-
-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 }>;
-}
-
-function require_streaming_assistant(
-  message: SessionMessage,
-): SessionAssistantMessage {
-  if (message.type !== "assistant") {
-    throw new Error(`Session Message is not assistant: ${message.message_id}`);
-  }
-  if (message.status !== "streaming") {
-    throw new Error(`Assistant Message is already closed: ${message.message_id}`);
-  }
-  return message;
+  return message as Extract<SessionMessage, { role: TRole }>;
 }
 
 function resolve_import_id(map: Map<string, string>, source_id: string, prefix: string): string {
@@ -1017,12 +752,15 @@ function resolve_import_id(map: Map<string, string>, source_id: string, prefix:
   return created;
 }
 
-/** 从 Action Message ID 提取稳定业务类型。 */
-function infer_action_type(message_id: string): string {
-  return String(message_id || "").split(":")[0] || "action";
-}
-
 /** 按真实 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),
+  );
 }