@downcity/agent 1.1.238 → 1.1.259

package/src/session/{recorder/SessionRecorder.ts → SessionMessages.ts}

@@ -1,17 +1,20 @@
 /**
- * SessionRecorder：Session Message 的唯一持久化与发布入口。
+ * SessionMessages：Session Message 的唯一领域入口。
  *
  * 完整 Message 与 Assistant 草稿先持久化，成功后再发布实时 Mutation。
+ * 同一 Assistant Message 的流式、审批与关闭操作共享一条写队列，保证 revision
+ * 从最新快照严格递增。
  */
 
-import type { UIMessage, UIMessageChunk } from "ai";
+import type { UIMessage } from "ai";
 import { generateId } from "@/utils/Id.js";
-import { JsonlSessionMessageStore } from "@/session/recorder/JsonlSessionMessageStore.js";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
+import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
+import { JsonlSessionMessageStore } from "@/session/messages/JsonlSessionMessageStore.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type {
   ListSessionMessagesInput,
   SessionActionMessage,
-  SessionAssistantFilePart,
   SessionAssistantMessage,
   SessionAssistantMessagePart,
   SessionAssistantToolPart,
@@ -30,104 +33,49 @@ import type {
   SessionMessageStorageStats,
   SessionSegmentSummary,
 } from "@/types/session/SessionSegment.js";
-
-/** SessionRecorder 构造参数。 */
-export interface SessionRecorderOptions {
-  /** 当前 Session 标识。 */
-  session_id: string;
-  /** Message 快照 store。 */
-  store: JsonlSessionMessageStore;
-  /** 持久化成功后的实时 Mutation 发布函数。 */
-  publish: (mutation: SessionMutation) => void;
-}
-
-/** User Message 创建参数。 */
-export interface AppendSessionUserMessageInput {
-  /** 当前输入所属 turn。 */
-  turn_id: string;
-  /** 普通 prompt 或 steering 输入。 */
-  input_type: "prompt" | "steer";
-  /** User 结构化 parts。 */
-  parts: SessionUserMessagePart[];
-  /** 可选指定 Message ID，通常由 Recorder 生成。 */
-  message_id?: string;
-  /** 默认展示范围。 */
-  visibility?: "visible" | "internal";
-}
-
-/** Assistant Message 创建参数。 */
-export interface OpenSessionAssistantMessageInput {
-  /** 当前 assistant 所属 turn。 */
-  turn_id: string;
-  /** 当前 assistant 在 turn 内的 segment 序号。 */
-  segment_index: number;
-  /** 普通 assistant 或 compact summary。 */
-  kind?: "normal" | "summary";
-  /** 默认展示范围。 */
-  visibility?: "visible" | "internal";
-  /** 可选指定 Message ID。 */
-  message_id?: string;
-  /** Summary 已覆盖到的来源 Message。 */
-  summary_through_message_id?: string;
-}
-
-/** 已完成 Assistant Message 直接写入参数。 */
-export interface AppendCompletedAssistantMessageInput {
-  /** Assistant 所属 turn。 */
-  turn_id?: string;
-  /** Assistant 完整 parts。 */
-  parts: SessionAssistantMessagePart[];
-  /** 普通 assistant 或 compact summary。 */
-  kind?: "normal" | "summary";
-  /** 默认展示范围。 */
-  visibility?: "visible" | "internal";
-  /** Summary 已覆盖到的来源 Message。 */
-  summary_through_message_id?: string;
-}
-
-/** Action Message 创建参数。 */
-export interface OpenSessionActionMessageInput {
-  /** 可选稳定 Message ID；业务 action 生命周期使用该值定位。 */
-  message_id?: string;
-  /** Action 所属 turn。 */
-  turn_id?: string;
-  /** Action 业务类型。 */
-  action_type: string;
-  /** Action 标题。 */
-  title: string;
-  /** Action 描述。 */
-  description?: string;
-  /** Action 附加数据。 */
-  data?: JsonObject;
-}
-
-/** Error Message 创建参数。 */
-export interface AppendSessionErrorMessageInput {
-  /** 错误影响范围。 */
-  scope: "session" | "turn";
-  /** 错误所属 turn。 */
-  turn_id?: string;
-  /** 稳定错误码。 */
-  code: string;
-  /** 用户可见错误文本。 */
-  message: string;
-  /** 是否允许恢复。 */
-  recoverable: boolean;
-}
+import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
+import type { SessionApproval } from "@/types/session/SessionApproval.js";
+import type {
+  SessionActionRecordV1,
+  SessionRecordV1,
+  SessionUserMessageV1,
+} from "@/executor/types/SessionRecords.js";
+import { is_session_action_record } from "@/executor/types/SessionRecords.js";
+import {
+  from_ui_assistant_parts,
+  from_ui_user_parts,
+  to_executor_ui_message,
+} from "@/session/messages/SessionMessageCodec.js";
+import { hydrateUserPromptFileParts } from "@executor/messages/SessionAttachmentMapper.js";
+import type {
+  AppendCompletedAssistantMessageInput,
+  AppendExternalSessionAssistantMessageInput,
+  AppendExternalSessionUserMessageInput,
+  AppendSessionErrorMessageInput,
+  AppendSessionPromptMessageInput,
+  AppendSessionUserMessageInput,
+  OpenSessionActionMessageInput,
+  OpenSessionAssistantMessageInput,
+  SessionMessagesOptions,
+} from "@/types/session/SessionMessages.js";
+
+export { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
 
 /** 唯一 Session Message 写入服务。 */
-export class SessionRecorder {
+export class SessionMessages {
   readonly session_id: string;
   private readonly store: JsonlSessionMessageStore;
-  private readonly publish: SessionRecorderOptions["publish"];
+  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>>();
   private initialized = false;
 
-  constructor(options: SessionRecorderOptions) {
+  constructor(options: SessionMessagesOptions) {
     this.session_id = String(options.session_id || "").trim();
     this.store = options.store;
     this.publish = options.publish;
-    if (!this.session_id) throw new Error("SessionRecorder requires session_id");
+    if (!this.session_id) throw new Error("SessionMessages requires session_id");
   }
 
   /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
@@ -224,6 +172,160 @@ export class SessionRecorder {
     return this.get_message(writer.message_id) as SessionAssistantMessage;
   }
 
+  /** 把内部 Executor Record 收口为 canonical Session Message。 */
+  async append_record(record: SessionRecordV1): Promise<void> {
+    if (is_session_action_record(record)) {
+      const action = record as SessionActionRecordV1;
+      const existing = this.get_message(action.id);
+      if (existing?.type === "action") {
+        if (action.state !== "running") {
+          await this.update_action_message(action.id, action.state, {
+            title: action.title,
+            description: action.description,
+          });
+        }
+        return;
+      }
+      const writer = await this.open_action_message({
+        message_id: action.id,
+        turn_id: action.metadata.turnId,
+        action_type: String(action.id || "").split(":")[0] || "action",
+        title: action.title,
+        description: action.description,
+      });
+      if (action.state === "completed") await writer.complete();
+      if (action.state === "failed") {
+        await writer.fail(action.description || action.title);
+      }
+      return;
+    }
+
+    const turn_id = String(
+      record.metadata?.turnId || `external:${this.session_id}:${generateId()}`,
+    );
+    if (record.role === "user") {
+      await this.append_user_message({
+        turn_id,
+        input_type:
+          record.metadata?.extra?.inputType === "steer" ? "steer" : "prompt",
+        parts: from_ui_user_parts(record.parts),
+      });
+      return;
+    }
+    await this.append_completed_assistant_message({
+      turn_id,
+      parts: from_ui_assistant_parts(record.parts),
+      visibility:
+        record.metadata?.extra?.visibility === "internal"
+          ? "internal"
+          : "visible",
+      kind: record.metadata?.kind === "summary" ? "summary" : "normal",
+    });
+  }
+
+  /** 把公开 Session API 的 User 输入转换为 canonical Message 并持久化。 */
+  async append_external_user_message(
+    input: AppendExternalSessionUserMessageInput,
+  ): Promise<boolean> {
+    const parts = input.message && "role" in input.message
+      ? from_ui_user_parts(input.message.parts)
+      : [{
+          part_id: `external-user-text:${Date.now()}`,
+          type: "text" as const,
+          text: String(input.text || "").trim(),
+          state: "done" as const,
+        }];
+    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,
+  ): Promise<boolean> {
+    const parts = input.message && "role" in input.message
+      ? from_ui_assistant_parts(input.message.parts)
+      : [{
+          part_id: `external-assistant-text:${Date.now()}`,
+          sequence: 1,
+          type: "text" as const,
+          text: String(input.fallback_text || "").trim(),
+          state: "done" as const,
+        }];
+    if (parts.length === 0) return false;
+    await this.append_completed_assistant_message({ parts });
+    return true;
+  }
+
+  /** 把 Session prompt 转换为 canonical User Message 并持久化。 */
+  async append_prompt_message(
+    input: AppendSessionPromptMessageInput,
+  ): Promise<SessionUserMessageV1> {
+    const query = input.prompt.query;
+    const ui_parts = typeof query === "string"
+      ? [{ type: "text" as const, text: query.trim() }]
+      : await hydrateUserPromptFileParts(
+          Array.isArray(query) ? query : [],
+          input.project_root,
+        );
+    const canonical = await this.append_user_message({
+      turn_id: input.turn_id,
+      input_type: input.input_type,
+      parts: normalize_session_user_parts(ui_parts),
+    });
+    return to_executor_ui_message(canonical) as SessionUserMessageV1;
+  }
+
+  /** 持久化 Executor 在本轮延迟产生的 User Message。 */
+  async append_deferred_user_messages(
+    deferred_messages?: SessionUserMessageV1[],
+  ): Promise<number> {
+    const messages = Array.isArray(deferred_messages)
+      ? deferred_messages
+      : [];
+    for (const message of messages) {
+      await this.append_user_message({
+        turn_id: String(
+          message.metadata?.turnId ||
+            `deferred:${this.session_id}:${Date.now()}`,
+        ),
+        input_type: "steer",
+        parts: from_ui_user_parts(message.parts),
+      });
+    }
+    return messages.length;
+  }
+
+  /** 按稳定 Action ID 创建或更新 canonical Action Message。 */
+  async persist_action_record(event: SessionActionRecordV1): Promise<void> {
+    const existing = this.get_message(event.id);
+    if (!existing) {
+      const writer = await this.open_action_message({
+        message_id: event.id,
+        turn_id: event.metadata.turnId,
+        action_type: infer_action_type(event.id),
+        title: event.title,
+        description: event.description,
+      });
+      if (event.state === "completed") await writer.complete();
+      if (event.state === "failed") {
+        await writer.fail(event.description || event.title);
+      }
+      return;
+    }
+    if (existing.type === "action" && event.state !== "running") {
+      await this.update_action_message(event.id, event.state, {
+        title: event.title,
+        description: event.description,
+      });
+    }
+  }
+
   /** 创建 running Action Message。 */
   async open_action_message(
     input: OpenSessionActionMessageInput,
@@ -416,6 +518,18 @@ export class SessionRecorder {
     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);
+    });
+  }
+
+  /** 在 Assistant 写队列内追加文本 delta。 */
+  private async append_assistant_delta_serialized(
+    message_id: string,
+    part_id: string,
+    type: "text" | "reasoning",
+    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);
@@ -453,6 +567,16 @@ export class SessionRecorder {
   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);
+    });
+  }
+
+  /** 在 Assistant 写队列内提交完整 Part 快照。 */
+  private async update_assistant_part_serialized(
+    message_id: string,
+    part: SessionAssistantMessagePart,
   ): Promise<void> {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
@@ -490,6 +614,16 @@ export class SessionRecorder {
   async complete_assistant_message(
     message_id: string,
     status: "completed" | "stopped" | "failed",
+  ): Promise<void> {
+    await this.enqueue_assistant_write(message_id, async () => {
+      await this.complete_assistant_message_serialized(message_id, status);
+    });
+  }
+
+  /** 在 Assistant 写队列内关闭草稿并写入 Active。 */
+  private async complete_assistant_message_serialized(
+    message_id: string,
+    status: "completed" | "stopped" | "failed",
   ): Promise<void> {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
@@ -509,42 +643,11 @@ export class SessionRecorder {
     this.accept_message(message);
   }
 
-  /** @internal 将 Shell Runtime 审批请求更新到当前 Tool Part。 */
-  async require_tool_approval(input: {
-    tool_call_id: string;
-    approval_id: string;
-  }): Promise<void> {
-    const tool = this.find_streaming_tool(input.tool_call_id);
-    await this.update_assistant_part(tool.message_id, {
-      ...tool.part,
-      state: "approval-required",
-      approval_id: input.approval_id,
-    });
-  }
-
-  /** @internal 将审批结果更新到当前 Tool Part。 */
-  async resolve_tool_approval(input: {
-    tool_call_id: string;
-    approval_id: string;
-    decision: "approved" | "denied" | "expired";
-  }): Promise<void> {
-    const tool = this.find_streaming_tool(input.tool_call_id);
-    if (tool.part.approval_id && tool.part.approval_id !== input.approval_id) {
-      throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
-    }
-    await this.update_assistant_part(tool.message_id, {
-      ...tool.part,
-      state: input.decision === "approved" ? "running" : "failed",
-      ...(input.decision === "approved"
-        ? {}
-        : { error: input.decision === "expired" ? "Approval expired" : "Approval denied" }),
-    });
-  }
-
   private async create_message(
     factory: (sequence: number, created_at: number) => SessionMessage,
     draft = false,
   ): 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());
@@ -563,10 +666,8 @@ export class SessionRecorder {
     return message;
   }
 
-  private find_streaming_tool(tool_call_id: string): {
-    message_id: string;
-    part: SessionAssistantToolPart;
-  } {
+  /** 读取当前流式 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(
@@ -575,6 +676,89 @@ export class SessionRecorder {
       );
       if (part) return { message_id: message.message_id, part };
     }
+    return undefined;
+  }
+
+  /** 把完整审批请求写入对应的流式 Tool Part。 */
+  async request_tool_approval(approval: SessionApproval): Promise<void> {
+    const { message_id } = this.require_streaming_tool(approval.tool_call_id);
+    await this.enqueue_assistant_write(message_id, async () => {
+      const tool = this.require_streaming_tool(approval.tool_call_id);
+      if (tool.message_id !== message_id) {
+        throw new Error(`Tool Assistant Message changed: ${approval.tool_call_id}`);
+      }
+      if (tool.part.state !== "ready") {
+        throw new Error(
+          `Tool approval requires ready input: ${approval.tool_call_id} (${tool.part.state})`,
+        );
+      }
+      await this.update_assistant_part_serialized(message_id, {
+        ...tool.part,
+        state: "approval-required",
+        approval,
+      });
+    });
+  }
+
+  /** 在 Tool 恢复执行前提交审批决定对应的 Part 状态。 */
+  async resolve_tool_approval(input: {
+    /** 当前审批请求标识。 */
+    approval_id: string;
+    /** 当前审批最终决定。 */
+    decision: "approved" | "denied" | "expired";
+    /** 当前审批关联的 Tool Call。 */
+    tool_call_id: string;
+  }): Promise<void> {
+    const { message_id } = this.require_streaming_tool(input.tool_call_id);
+    await this.enqueue_assistant_write(message_id, async () => {
+      const tool = this.require_streaming_tool(input.tool_call_id);
+      if (tool.message_id !== message_id) {
+        throw new Error(`Tool Assistant Message changed: ${input.tool_call_id}`);
+      }
+      if (tool.part.approval?.approval_id !== input.approval_id) {
+        throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
+      }
+      await this.update_assistant_part_serialized(message_id, {
+        ...tool.part,
+        state: input.decision === "approved" ? "running" : "failed",
+        ...(input.decision === "approved"
+          ? {}
+          : {
+              error:
+                input.decision === "expired"
+                  ? "Approval expired"
+                  : "Approval denied",
+            }),
+      });
+    });
+  }
+
+  /**
+   * 串行执行同一 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);
+      }
+    }
+  }
+
+  /** 查找当前流式 Assistant 中的 Tool Part，否则抛出明确错误。 */
+  private require_streaming_tool(tool_call_id: string): SessionStreamingToolLocation {
+    const tool = this.find_streaming_tool(tool_call_id);
+    if (tool) return tool;
     throw new Error(`Streaming Tool Part not found: ${tool_call_id}`);
   }
 
@@ -609,311 +793,28 @@ export class SessionRecorder {
   }
 
 }
-
-/** 单个 Assistant segment 的流式 writer。 */
-export class SessionAssistantMessageWriter {
-  readonly message_id: string;
-  private readonly recorder: SessionRecorder;
-  private readonly pending_text_parts = new Map<string, "text" | "reasoning">();
-  private readonly active_text_part_ids = new Map<string, string>();
-  private closed = false;
-
-  constructor(recorder: SessionRecorder, message_id: string) {
-    this.recorder = recorder;
-    this.message_id = message_id;
-  }
-
-  /** 应用一个原始 AI SDK UI chunk。 */
-  async apply_chunk(chunk: UIMessageChunk): Promise<void> {
-    if (this.closed) throw new Error("Assistant Message writer is closed");
-    const current = this.current_message();
-    switch (chunk.type) {
-      case "text-start":
-      case "reasoning-start": {
-        const type = chunk.type === "text-start" ? "text" : "reasoning";
-        const part_id = this.resolve_text_part_id(type, chunk.id);
-        if (!current.parts.some((part) => part.part_id === part_id)) {
-          this.pending_text_parts.set(part_id, type);
-        }
-        return;
-      }
-      case "text-delta":
-      case "reasoning-delta": {
-        const type = chunk.type === "text-delta" ? "text" : "reasoning";
-        const part_id = this.resolve_text_part_id(type, chunk.id);
-        await this.ensure_text_part(part_id, type);
-        await this.recorder.append_assistant_delta(
-          this.message_id,
-          part_id,
-          type,
-          chunk.delta,
-        );
-        return;
-      }
-      case "text-end":
-      case "reasoning-end": {
-        const type = chunk.type === "text-end" ? "text" : "reasoning";
-        const source_part_id = this.source_text_part_id(type, chunk.id);
-        const part_id = this.active_text_part_ids.get(source_part_id);
-        if (!part_id) return;
-        const part = current.parts.find((item) => item.part_id === part_id);
-        if (part?.type === "text" || part?.type === "reasoning") {
-          await this.upsert_part({ ...part, state: "done" });
-        } else {
-          this.pending_text_parts.delete(part_id);
-        }
-        this.active_text_part_ids.delete(source_part_id);
-        return;
-      }
-      case "tool-input-start":
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: chunk.toolName,
-          state: "input-streaming",
-          input_text: "",
-        });
-        return;
-      case "tool-input-delta": {
-        const tool = this.find_tool(chunk.toolCallId);
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: tool?.tool_name || "unknown",
-          state: "input-streaming",
-          input_text: `${tool?.input_text || ""}${chunk.inputTextDelta}`,
-        });
-        return;
-      }
-      case "tool-input-available":
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: chunk.toolName,
-          state: "ready",
-          input: to_json_value(chunk.input),
-        });
-        return;
-      case "tool-input-error":
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: chunk.toolName,
-          state: "failed",
-          input: to_json_value(chunk.input),
-          error: chunk.errorText,
-        });
-        return;
-      case "tool-approval-request": {
-        const tool = this.find_tool(chunk.toolCallId);
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: tool?.tool_name || "unknown",
-          state: "approval-required",
-          approval_id: chunk.approvalId,
-        });
-        return;
-      }
-      case "tool-output-available": {
-        const tool = this.find_tool(chunk.toolCallId);
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: tool?.tool_name || "unknown",
-          state: "completed",
-          output: to_json_value(chunk.output),
-        });
-        return;
-      }
-      case "tool-output-error":
-      case "tool-output-denied": {
-        const tool = this.find_tool(chunk.toolCallId);
-        await this.upsert_tool(chunk.toolCallId, {
-          tool_name: tool?.tool_name || "unknown",
-          state: "failed",
-          error:
-            chunk.type === "tool-output-error"
-              ? chunk.errorText
-              : "Tool output denied",
-        });
-        return;
-      }
-      case "file":
-        await this.append_file_part({
-          media_type: chunk.mediaType,
-          url: chunk.url,
-        });
-        return;
-      default:
-        return;
-    }
-  }
-
-  /** 写入一个完整 Assistant part。 */
-  async upsert_part(part: SessionAssistantMessagePart): Promise<void> {
-    await this.recorder.update_assistant_part(this.message_id, part);
-  }
-
-  /**
-   * 把最终结果中的文件补入当前 Assistant，并对流式已写入文件去重。
-   */
-  async append_file_part(
-    input: Pick<SessionAssistantFilePart, "filename" | "media_type" | "url">,
-  ): Promise<void> {
-    const filename = String(input.filename || "").trim();
-    const current = this.current_message();
-    const existing = current.parts.find(
-      (part) =>
-        part.type === "file" &&
-        part.url === input.url &&
-        part.media_type === input.media_type,
-    );
-    if (existing?.type === "file") {
-      if (filename && String(existing.filename || "").trim() !== filename) {
-        await this.upsert_part({ ...existing, filename });
-      }
-      return;
-    }
-    await this.upsert_part({
-      part_id: `file:${generateId()}`,
-      sequence: this.next_part_sequence(),
-      type: "file",
-      media_type: input.media_type,
-      url: input.url,
-      ...(filename ? { filename } : {}),
-    });
-  }
-
-  /** 当前实现逐 chunk 等待落盘，因此 flush 在返回时天然完成。 */
-  async flush(): Promise<void> {}
-
-  /** 正常完成当前 assistant segment。 */
-  async complete(): Promise<void> {
-    await this.close("completed");
-  }
-
-  /** 停止当前 assistant segment，并保留已有 parts。 */
-  async stop(): Promise<void> {
-    await this.close("stopped");
-  }
-
-  /** 以失败状态关闭当前 assistant segment。 */
-  async fail(_error: unknown): Promise<void> {
-    await this.close("failed");
-  }
-
-  private current_message(): SessionAssistantMessage {
-    const message = this.recorder.get_message(this.message_id);
-    if (!message || message.type !== "assistant") {
-      throw new Error(`Assistant Message not found: ${this.message_id}`);
-    }
-    return message;
-  }
-
-  private find_tool(tool_call_id: string): SessionAssistantToolPart | undefined {
-    return this.current_message().parts.find(
-      (part): part is SessionAssistantToolPart =>
-        part.type === "tool" && part.tool_call_id === tool_call_id,
-    );
-  }
-
-  private next_part_sequence(): number {
-    return this.current_message().parts.reduce(
-      (value, part) => Math.max(value, part.sequence + 1),
-      1,
-    );
-  }
-
-  /**
-   * 把 AI SDK 当前 stream 内的临时 chunk ID 映射为 Message 内唯一 Part ID。
-   *
-   * AI SDK 会在不同 `streamText()` 调用中重复使用 `txt-0`、`reasoning-0`
-   * 等 ID，因此这些 ID 只能用于关联当前尚未结束的文本片段。
-   */
-  private resolve_text_part_id(
-    type: "text" | "reasoning",
-    chunk_id: string,
-  ): string {
-    const source_part_id = this.source_text_part_id(type, chunk_id);
-    const active_part_id = this.active_text_part_ids.get(source_part_id);
-    if (active_part_id) return active_part_id;
-    const part_id = `${type}:${generateId()}`;
-    this.active_text_part_ids.set(source_part_id, part_id);
-    return part_id;
-  }
-
-  /** 构造当前流片段使用的临时关联键。 */
-  private source_text_part_id(
-    type: "text" | "reasoning",
-    chunk_id: string,
-  ): string {
-    return `${type}:${chunk_id}`;
-  }
-
-  /** 在首个有效 Delta 到达时才固定文本 Part 的真实顺序。 */
-  private async ensure_text_part(
-    part_id: string,
-    type: "text" | "reasoning",
-  ): Promise<void> {
-    const existing = this.current_message().parts.find(
-      (part) => part.part_id === part_id,
-    );
-    if (existing) {
-      if (existing.type !== type) {
-        throw new Error(`Assistant Part type changed: ${part_id}`);
-      }
-      return;
-    }
-    const pending_type = this.pending_text_parts.get(part_id);
-    if (pending_type && pending_type !== type) {
-      throw new Error(`Assistant pending Part type changed: ${part_id}`);
-    }
-    await this.upsert_part({
-      part_id,
-      sequence: this.next_part_sequence(),
-      type,
-      text: "",
-      state: "streaming",
-    });
-    this.pending_text_parts.delete(part_id);
-  }
-
-  private async upsert_tool(
-    tool_call_id: string,
-    changes: Pick<SessionAssistantToolPart, "tool_name" | "state"> &
-      Partial<Omit<SessionAssistantToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
-  ): Promise<void> {
-    const current = this.find_tool(tool_call_id);
-    await this.upsert_part({
-      ...(current || {}),
-      part_id: `tool:${tool_call_id}`,
-      sequence: current?.sequence || this.next_part_sequence(),
-      type: "tool",
-      tool_call_id,
-      ...changes,
-    });
-  }
-
-  private async close(status: "completed" | "stopped" | "failed"): Promise<void> {
-    if (this.closed) return;
-    this.pending_text_parts.clear();
-    this.active_text_part_ids.clear();
-    await this.recorder.complete_assistant_message(this.message_id, status);
-    this.closed = true;
-  }
-}
-
 /** 单个 Action Message 的生命周期 writer。 */
 export class SessionActionMessageWriter {
   readonly message_id: string;
-  private readonly recorder: SessionRecorder;
+  private readonly messages: SessionMessages;
   private closed = false;
 
-  constructor(recorder: SessionRecorder, message_id: string) {
-    this.recorder = recorder;
+  constructor(messages: SessionMessages, message_id: string) {
+    this.messages = messages;
     this.message_id = message_id;
   }
 
   /** 把 Action 更新为 completed。 */
   async complete(input?: { title?: string; description?: string; data?: JsonObject }): Promise<void> {
     if (this.closed) return;
-    await this.recorder.update_action_message(this.message_id, "completed", input);
+    await this.messages.update_action_message(this.message_id, "completed", input);
     this.closed = true;
   }
 
   /** 把 Action 更新为 failed。 */
   async fail(error: unknown): Promise<void> {
     if (this.closed) return;
-    await this.recorder.update_action_message(this.message_id, "failed", {
+    await this.messages.update_action_message(this.message_id, "failed", {
       description: error instanceof Error ? error.message : String(error),
     });
     this.closed = true;
@@ -950,7 +851,7 @@ export function normalize_session_user_parts(
         part_id: `user-data:${index + 1}`,
         type: "data",
         data_type: String(candidate.type),
-        data: to_json_value(candidate.data),
+        data: to_session_json_value(candidate.data),
       }];
     }
     return [];
@@ -981,16 +882,6 @@ function require_streaming_assistant(
   return message;
 }
 
-function to_json_value(input: unknown): JsonValue {
-  if (input === undefined || input === null) return null;
-  if (typeof input === "string" || typeof input === "number" || typeof input === "boolean") return input;
-  try {
-    return JSON.parse(JSON.stringify(input)) as JsonValue;
-  } catch {
-    return String(input);
-  }
-}
-
 function resolve_import_id(map: Map<string, string>, source_id: string, prefix: string): string {
   const existing = map.get(source_id);
   if (existing) return existing;
@@ -999,6 +890,11 @@ 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;