@downcity/agent 1.1.430 → 1.1.437

package/src/session/messages/{SessionAssistantMessageWriter.ts → SessionAgentMessageWriter.ts}

@@ -9,20 +9,22 @@ import type { ModelStreamEvent } from "@downcity/type";
 import type { SessionMessages } from "@/session/SessionMessages.js";
 import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
 import { SessionToolPartGate } from "@/session/messages/SessionToolPartGate.js";
-import type { SessionAssistantResultPart } from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
 import type {
-  SessionAssistantMessage,
-  SessionAssistantMessagePart,
-  SessionAssistantToolPart,
+  SessionAgentErrorPart,
+  SessionAgentMessage,
+  SessionAgentMessagePart,
+  SessionAgentToolPart,
 } from "@downcity/type";
 import type {
   SessionToolExecutionResult,
   SessionToolInputReady,
 } from "@/types/session/SessionTool.js";
 import { generate_id } from "@/utils/Id.js";
+import { create_session_agent_content_part } from "@/session/messages/SessionAgentContent.js";
 
 /** 单个 Assistant Message 的流式 Writer。 */
-export class SessionAssistantMessageWriter {
+export class SessionAgentMessageWriter {
   /** 当前 canonical Assistant Message 标识。 */
   readonly message_id: string;
 
@@ -33,6 +35,7 @@ export class SessionAssistantMessageWriter {
   private readonly tool_part_gate = new SessionToolPartGate();
   private write_chain: Promise<void> = Promise.resolve();
   private step_index = 0;
+  private current_step_id: string | null = null;
   private step_active = false;
   private closed = false;
 
@@ -49,6 +52,7 @@ export class SessionAssistantMessageWriter {
         throw new Error("Assistant canonical step is already active");
       }
       this.step_index += 1;
+      this.current_step_id = `step:${this.message_id}:${this.step_index}`;
       this.step_active = true;
       this.content_part_ids.clear();
       this.tool_call_ids.clear();
@@ -81,6 +85,7 @@ export class SessionAssistantMessageWriter {
         state: "ready",
         input: to_session_json_value(input.input),
       });
+      await this.recorder.checkpoint_agent_message(this.message_id);
     });
   }
 
@@ -100,6 +105,7 @@ export class SessionAssistantMessageWriter {
             state: "failed",
             error: read_tool_error(result.output),
           });
+      await this.recorder.checkpoint_agent_message(this.message_id);
     });
   }
 
@@ -108,7 +114,7 @@ export class SessionAssistantMessageWriter {
    *
    * 最终快照不能创建、删除或重排模型 Part；不一致意味着事件链不完整。
    */
-  async finish_step(parts: SessionAssistantMessagePart[]): Promise<void> {
+  async finish_step(parts: SessionAgentMessagePart[]): Promise<void> {
     await this.enqueue_write(async () => {
       if (!this.step_active) {
         throw new Error("Assistant canonical step is not active");
@@ -122,7 +128,7 @@ export class SessionAssistantMessageWriter {
           `part count ${current_parts.length} != ${parts.length}`,
         );
       }
-      const merged_parts = new Map<string, SessionAssistantMessagePart>();
+      const merged_parts = new Map<string, SessionAgentMessagePart>();
       for (let index = 0; index < current_parts.length; index += 1) {
         const current_part = current_parts[index];
         const final_part = parts[index];
@@ -131,7 +137,7 @@ export class SessionAssistantMessageWriter {
           this.merge_step_part(current_part, final_part, index),
         );
       }
-      await this.recorder.commit_assistant_step(
+      await this.recorder.commit_agent_step(
         this.message_id,
         current.parts.map((part) => merged_parts.get(part.part_id) ?? part),
       );
@@ -139,53 +145,66 @@ export class SessionAssistantMessageWriter {
     });
   }
 
-  /** 释放异常结束的 Step 作用域并保留已经写入的 canonical Parts。 */
+  /** 释放异常 Step，并丢弃最近检查点之后的运行投影。 */
   async abort_step(): Promise<void> {
     await this.enqueue_write(async () => {
       this.tool_part_gate.reject_pending("Assistant canonical step was aborted");
-      if (this.step_active) this.reset_step_state();
+      if (this.step_active) {
+        await this.recorder.rollback_agent_projection(this.message_id);
+        this.reset_step_state();
+      }
     });
   }
 
   /** 把 Action 产生的封闭内容追加到当前 Assistant Message。 */
-  async append_result_parts(parts: readonly SessionAssistantResultPart[]): Promise<void> {
-    await this.enqueue_write(async () => {
+  async append_result_parts(parts: readonly SessionAgentContent[]): Promise<SessionAgentMessagePart[]> {
+    return await this.enqueue_write(async () => {
       if (this.closed) throw new Error("Assistant Message writer is closed");
+      const appended_parts: SessionAgentMessagePart[] = [];
+      let sequence = this.next_part_sequence();
       for (const part of parts) {
-        if (part.type === "text") {
-          await this.upsert_part({
-            part_id: `text:${generate_id()}`,
-            sequence: this.next_part_sequence(),
-            type: "text",
-            text: part.text,
-            state: "done",
-          });
-        } else if (part.type === "file") {
-          await this.upsert_part({
-            part_id: `file:${generate_id()}`,
-            sequence: this.next_part_sequence(),
-            type: "file",
-            media_type: part.media_type,
-            url: part.url,
-            ...(part.filename ? { filename: part.filename } : {}),
-          });
-        } else {
-          await this.upsert_part({
-            part_id: `data:${generate_id()}`,
-            sequence: this.next_part_sequence(),
-            type: "data",
-            data_type: part.data_type,
-            data: part.data,
-            ...(part.data_id ? { data_id: part.data_id } : {}),
-          });
-        }
+        const canonical = create_session_agent_content_part(
+          part,
+          `${part.type}:${generate_id()}`,
+          sequence,
+        );
+        appended_parts.push(canonical);
+        sequence += 1;
       }
+      await this.recorder.commit_agent_parts(this.message_id, appended_parts);
+      return appended_parts;
+    });
+  }
+
+  /** 在 Turn 收口产物之前追加用户可见的 canonical Error Part。 */
+  async append_error(input: {
+    /** 错误影响范围。 */
+    scope: "session" | "turn";
+    /** 稳定错误码。 */
+    code: string;
+    /** 用户可见错误信息。 */
+    message: string;
+    /** 当前错误是否允许重试恢复。 */
+    recoverable: boolean;
+  }): Promise<void> {
+    await this.enqueue_write(async () => {
+      if (this.closed) throw new Error("Assistant Message writer is closed");
+      const part = {
+        part_id: `error:${generate_id()}`,
+        sequence: this.next_part_sequence(),
+        type: "error",
+        scope: input.scope,
+        code: input.code,
+        message: input.message,
+        recoverable: input.recoverable,
+      } satisfies SessionAgentErrorPart;
+      await this.recorder.commit_agent_parts(this.message_id, [part]);
     });
   }
 
   /** 写入一个完整 canonical Assistant Part。 */
-  async upsert_part(part: SessionAssistantMessagePart): Promise<void> {
-    await this.recorder.update_assistant_part(this.message_id, part);
+  async upsert_part(part: SessionAgentMessagePart): Promise<void> {
+    this.recorder.project_agent_part(this.message_id, part);
     if (this.step_active) this.current_step_part_ids.add(part.part_id);
   }
 
@@ -224,6 +243,7 @@ export class SessionAssistantMessageWriter {
       await this.upsert_part({
         part_id,
         sequence: this.next_part_sequence(),
+        step_id: this.require_step_id(),
         type,
         text: "",
         state: "streaming",
@@ -234,7 +254,7 @@ export class SessionAssistantMessageWriter {
       if (!event.delta) return;
       const type = event.type === "text_delta" ? "text" : "reasoning";
       const part_id = this.require_content_part_id(event.content_id);
-      await this.recorder.append_assistant_delta(
+      this.recorder.project_agent_delta(
         this.message_id,
         part_id,
         type,
@@ -271,7 +291,7 @@ export class SessionAssistantMessageWriter {
       if (!event.input_delta) return;
       const tool_call_id = this.require_tool_call_id(event.content_id);
       const tool = this.require_tool(tool_call_id);
-      await this.recorder.append_assistant_tool_input_delta(
+      this.recorder.project_agent_tool_input_delta(
         this.message_id,
         tool.part_id,
         tool_call_id,
@@ -292,24 +312,24 @@ export class SessionAssistantMessageWriter {
   }
 
   /** 读取当前 Assistant Message 快照。 */
-  private current_message(): SessionAssistantMessage {
+  private current_message(): SessionAgentMessage {
     const message = this.recorder.get_message(this.message_id);
-    if (!message || message.type !== "assistant") {
+    if (!message || message.role !== "agent") {
       throw new Error(`Assistant Message not found: ${this.message_id}`);
     }
     return message;
   }
 
   /** 查找当前 Assistant 中的指定 Tool Part。 */
-  private find_tool(tool_call_id: string): SessionAssistantToolPart | undefined {
+  private find_tool(tool_call_id: string): SessionAgentToolPart | undefined {
     return this.current_message().parts.find(
-      (part): part is SessionAssistantToolPart =>
+      (part): part is SessionAgentToolPart =>
         part.type === "tool" && part.tool_call_id === tool_call_id,
     );
   }
 
   /** 读取指定 Tool Part，否则抛出稳定错误。 */
-  private require_tool(tool_call_id: string): SessionAssistantToolPart {
+  private require_tool(tool_call_id: string): SessionAgentToolPart {
     const tool = this.find_tool(tool_call_id);
     if (tool) return tool;
     throw new Error(`Assistant canonical Tool Part not found: ${tool_call_id}`);
@@ -332,8 +352,8 @@ export class SessionAssistantMessageWriter {
   /** 更新已经由模型事件创建的 Tool Part。 */
   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">>,
+    changes: Pick<SessionAgentToolPart, "tool_name" | "state"> &
+      Partial<Omit<SessionAgentToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
   ): Promise<void> {
     const current = this.require_tool(tool_call_id);
     await this.upsert_part({ ...current, ...changes });
@@ -342,8 +362,8 @@ export class SessionAssistantMessageWriter {
   /** 创建由模型事件声明的 Tool Part。 */
   private async create_tool(
     tool_call_id: string,
-    changes: Pick<SessionAssistantToolPart, "tool_name" | "state"> &
-      Partial<Omit<SessionAssistantToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
+    changes: Pick<SessionAgentToolPart, "tool_name" | "state"> &
+      Partial<Omit<SessionAgentToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
   ): Promise<void> {
     if (this.find_tool(tool_call_id)) {
       throw new Error(`Assistant canonical Tool Part already exists: ${tool_call_id}`);
@@ -351,6 +371,7 @@ export class SessionAssistantMessageWriter {
     await this.upsert_part({
       part_id: `tool:${tool_call_id}`,
       sequence: this.next_part_sequence(),
+      step_id: this.require_step_id(),
       type: "tool",
       tool_call_id,
       ...changes,
@@ -359,10 +380,10 @@ export class SessionAssistantMessageWriter {
 
   /** 校验并合并同一位置的 canonical Part 与 Step 最终快照。 */
   private merge_step_part(
-    current_part: SessionAssistantMessagePart,
-    final_part: SessionAssistantMessagePart,
+    current_part: SessionAgentMessagePart,
+    final_part: SessionAgentMessagePart,
     index: number,
-  ): SessionAssistantMessagePart {
+  ): SessionAgentMessagePart {
     if (current_part.type !== final_part.type) {
       throw this.step_snapshot_error(
         `part ${index + 1} type ${current_part.type} != ${final_part.type}`,
@@ -387,7 +408,8 @@ export class SessionAssistantMessageWriter {
       ...final_part,
       part_id: current_part.part_id,
       sequence: current_part.sequence,
-    } as SessionAssistantMessagePart;
+      step_id: current_part.step_id,
+    } as SessionAgentMessagePart;
   }
 
   /** 构造不包含正文与 Tool 输出的结构化 Step 快照错误。 */
@@ -400,11 +422,18 @@ export class SessionAssistantMessageWriter {
   /** 清理当前 Step 的临时关联状态。 */
   private reset_step_state(): void {
     this.step_active = false;
+    this.current_step_id = null;
     this.content_part_ids.clear();
     this.tool_call_ids.clear();
     this.current_step_part_ids.clear();
   }
 
+  /** 返回当前模型 Step 的稳定标识。 */
+  private require_step_id(): string {
+    if (this.step_active && this.current_step_id) return this.current_step_id;
+    throw new Error("Assistant canonical step is not active");
+  }
+
   /** 计算下一个不可变 Part 顺序号。 */
   private next_part_sequence(): number {
     return this.current_message().parts.reduce(
@@ -414,10 +443,10 @@ export class SessionAssistantMessageWriter {
   }
 
   /** 串行执行对当前 Assistant Message 的全部写操作。 */
-  private async enqueue_write(operation: () => Promise<void>): Promise<void> {
+  private async enqueue_write<TResult>(operation: () => Promise<TResult>): Promise<TResult> {
     const current = this.write_chain.then(operation, operation);
-    this.write_chain = current.catch(() => undefined);
-    await current;
+    this.write_chain = current.then(() => undefined, () => undefined);
+    return await current;
   }
 
   /** 在队列内关闭当前 Assistant Message。 */
@@ -430,7 +459,7 @@ export class SessionAssistantMessageWriter {
       `Assistant Message writer closed with status ${status}`,
     );
     this.reset_step_state();
-    await this.recorder.complete_assistant_message(this.message_id, status, error);
+    await this.recorder.complete_agent_message(this.message_id, status, error);
     this.closed = true;
   }
 }

package/src/session/messages/SessionForkMessageFiles.ts

@@ -4,6 +4,31 @@ import path from "node:path";
 import type { SessionMessage } from "@downcity/type";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
+/** 截取 Fork 锚点之前的历史，并按调用语义决定是否包含锚点。 */
+export function resolve_session_fork_messages(input: {
+  /** 当前源 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前源 Session 的完整 canonical 历史。 */
+  messages: SessionMessage[];
+  /** Fork 使用的锚点 Message 标识。 */
+  message_id: string;
+  /** Fork 历史是否包含锚点 Message 本身。 */
+  include_message: boolean;
+}): SessionMessage[] {
+  const target_index = input.messages.findIndex(
+    (message) => message.message_id === input.message_id,
+  );
+  if (target_index < 0) {
+    throw new Error(
+      `Cannot fork session "${input.session_id}": message_id "${input.message_id}" not found.`,
+    );
+  }
+  return input.messages.slice(
+    0,
+    input.include_message ? target_index + 1 : target_index,
+  );
+}
+
 /**
  * 将 fork 历史中的本地绝对路径复制到目标 Session 的附件 Store。
  *
@@ -17,7 +42,6 @@ export async function relocate_fork_message_files(
 ): Promise<SessionMessage[]> {
   const relocated_urls = new Map<string, Promise<string>>();
   return await Promise.all(messages.map(async (message) => {
-    if (message.type !== "user" && message.type !== "assistant") return structuredClone(message);
     const parts = await Promise.all(message.parts.map(async (part) => {
       if (part.type !== "file") return structuredClone(part);
       if (!part.url.startsWith("data:") && (!path.isAbsolute(part.url) || !source_store.owns_local_file(part.url))) {

package/src/session/messages/SessionMessageInteractionWriter.ts

@@ -7,9 +7,9 @@
  */
 
 import type {
-  SessionAssistantInteractionPart,
-  SessionAssistantMessage,
-  SessionAssistantMessagePart,
+  SessionAgentInteractionPart,
+  SessionAgentMessage,
+  SessionAgentMessagePart,
   SessionMessage,
 } from "@downcity/type";
 import type {
@@ -34,8 +34,8 @@ interface SessionMessageInteractionWriterOptions {
   ) => Promise<T>;
   /** 原子持久化 Assistant 完整快照并发布发生变化的 Part。 */
   commit_assistant_snapshot: (
-    current: SessionAssistantMessage,
-    parts: SessionAssistantMessagePart[],
+    current: SessionAgentMessage,
+    parts: SessionAgentMessagePart[],
   ) => Promise<void>;
 }
 
@@ -48,9 +48,9 @@ export class SessionMessageInteractionWriter {
   }
 
   /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
-  list_pending(): SessionAssistantInteractionPart[] {
+  list_pending(): SessionAgentInteractionPart[] {
     return [...this.options.list_messages()].flatMap((message) =>
-      message.type === "assistant" && message.status === "streaming"
+      message.role === "agent" && message.state === "streaming"
         ? message.parts.flatMap((part) =>
             part.type === "interaction" && part.status === "pending"
               ? [structuredClone(part)]
@@ -63,7 +63,7 @@ export class SessionMessageInteractionWriter {
   /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
   async request(
     request: SessionInteractionRequest,
-  ): Promise<SessionAssistantInteractionPart> {
+  ): Promise<SessionAgentInteractionPart> {
     const tool_call_id = request.source.tool_call_id;
     const message_id = tool_call_id
       ? this.require_streaming_tool(tool_call_id).message_id
@@ -102,7 +102,7 @@ export class SessionMessageInteractionWriter {
         }
       }
 
-      const interaction: SessionAssistantInteractionPart = {
+      const interaction: SessionAgentInteractionPart = {
         part_id: `interaction:${request.interaction_id}`,
         sequence: parts.reduce(
           (sequence, part) => Math.max(sequence, part.sequence + 1),
@@ -123,7 +123,7 @@ export class SessionMessageInteractionWriter {
   async resolve(
     interaction_id: string,
     response: SessionInteractionResponse,
-  ): Promise<SessionAssistantInteractionPart> {
+  ): Promise<SessionAgentInteractionPart> {
     const { message_id } = this.require_pending_interaction(interaction_id);
     await this.options.enqueue_assistant_write(message_id, async () => {
       const current = this.require_streaming_assistant(message_id);
@@ -171,7 +171,7 @@ export class SessionMessageInteractionWriter {
   async close(
     interaction_id: string,
     input: SessionInteractionCloseInput,
-  ): Promise<SessionAssistantInteractionPart> {
+  ): Promise<SessionAgentInteractionPart> {
     const { message_id } = this.require_pending_interaction(interaction_id);
     await this.options.enqueue_assistant_write(message_id, async () => {
       const current = this.require_streaming_assistant(message_id);
@@ -209,15 +209,15 @@ export class SessionMessageInteractionWriter {
   /** 读取指定或当前唯一的流式 Assistant Message。 */
   private require_streaming_assistant(
     message_id?: string,
-  ): SessionAssistantMessage {
+  ): SessionAgentMessage {
     const message = message_id
       ? [...this.options.list_messages()].find(
           (item) => item.message_id === message_id,
         )
       : [...this.options.list_messages()].find(
-          (item) => item.type === "assistant" && item.status === "streaming",
+          (item) => item.role === "agent" && item.state === "streaming",
         );
-    if (!message || message.type !== "assistant" || message.status !== "streaming") {
+    if (!message || message.role !== "agent" || message.state !== "streaming") {
       throw new Error(
         message_id
           ? `Streaming Assistant Message not found: ${message_id}`
@@ -231,13 +231,13 @@ export class SessionMessageInteractionWriter {
   private find_interaction(interaction_id: string):
     | {
         message_id: string;
-        part: SessionAssistantInteractionPart;
+        part: SessionAgentInteractionPart;
       }
     | undefined {
     for (const message of this.options.list_messages()) {
-      if (message.type !== "assistant" || message.status !== "streaming") continue;
+      if (message.role !== "agent" || message.state !== "streaming") continue;
       const part = message.parts.find(
-        (item): item is SessionAssistantInteractionPart =>
+        (item): item is SessionAgentInteractionPart =>
           item.type === "interaction" &&
           item.interaction_id === interaction_id,
       );
@@ -249,7 +249,7 @@ export class SessionMessageInteractionWriter {
   /** 读取指定 Interaction，否则抛出稳定领域错误。 */
   private require_interaction(interaction_id: string): {
     message_id: string;
-    part: SessionAssistantInteractionPart;
+    part: SessionAgentInteractionPart;
   } {
     const interaction = this.find_interaction(interaction_id);
     if (interaction) return interaction;
@@ -259,7 +259,7 @@ export class SessionMessageInteractionWriter {
   /** 读取指定 pending Interaction，否则拒绝重复响应终态 Interaction。 */
   private require_pending_interaction(interaction_id: string): {
     message_id: string;
-    part: SessionAssistantInteractionPart;
+    part: SessionAgentInteractionPart;
   } {
     const interaction = this.require_interaction(interaction_id);
     if (interaction.part.status !== "pending") {

package/src/session/messages/SessionMessageText.ts

@@ -5,7 +5,7 @@
  */
 
 import type {
-  SessionAssistantMessage,
+  SessionAgentMessage,
   SessionMessage,
 } from "@downcity/type";
 import type { JsonObject, JsonValue } from "@downcity/type";
@@ -24,7 +24,6 @@ export interface SessionToolCallSummary {
 
 /** 提取单条 canonical Message 的全部普通文本。 */
 export function extract_session_message_text(message: SessionMessage): string {
-  if (message.type !== "user" && message.type !== "assistant") return "";
   return message.parts
     .flatMap((part) => part.type === "text" ? [part.text] : [])
     .map((text) => text.trim())
@@ -35,7 +34,7 @@ export function extract_session_message_text(message: SessionMessage): string {
 
 /** 提取 Assistant Message 中的 canonical 工具调用摘要。 */
 export function extract_session_tool_calls(
-  message: SessionAssistantMessage,
+  message: SessionAgentMessage,
 ): SessionToolCallSummary[] {
   return message.parts.flatMap((part) => {
     if (part.type !== "tool" || part.input === undefined) return [];
@@ -52,7 +51,7 @@ export function extract_session_tool_calls(
 
 /** 读取最终一次成功 `chat_send` 的可见文本，并回退到普通 Assistant 文本。 */
 export function resolve_session_assistant_visible_text(
-  message: SessionAssistantMessage,
+  message: SessionAgentMessage,
 ): string {
   const calls = extract_session_tool_calls(message);
   for (let index = calls.length - 1; index >= 0; index -= 1) {

package/src/session/messages/SessionTurnFileDiffData.ts

@@ -5,7 +5,7 @@
  * 任意 JSON 结构。
  */
 
-import type { SessionAssistantDataPart } from "@downcity/type";
+import type { SessionAgentDataPart } from "@downcity/type";
 import type {
   SessionTurnFileDiff,
   SessionTurnFileDiffData,
@@ -17,7 +17,7 @@ export const SESSION_TURN_FILE_DIFF_DATA_TYPE = "data-session-turn-file-diff";
 
 /** 从 Assistant data part 中读取经过校验的 Turn 文件改动。 */
 export function read_session_turn_file_diff_data(
-  part: SessionAssistantDataPart,
+  part: SessionAgentDataPart,
 ): SessionTurnFileDiffData | undefined {
   if (part.data_type !== SESSION_TURN_FILE_DIFF_DATA_TYPE) return undefined;
   if (!is_record(part.data) || !Array.isArray(part.data.files)) return undefined;
@@ -34,7 +34,7 @@ export function read_session_turn_file_diff_data(
 
 /** 判断 data part 是否为有效的 Turn 文件改动。 */
 export function is_session_turn_file_diff_data_part(
-  part: SessionAssistantDataPart,
+  part: SessionAgentDataPart,
 ): boolean {
   return read_session_turn_file_diff_data(part) !== undefined;
 }

package/src/session/messages/SessionUserMessage.ts

@@ -5,8 +5,8 @@
  */
 
 import type {
-  SessionAssistantResultPart,
-  SessionPromptPart,
+  SessionAgentContent,
+  SessionUserContent,
 } from "@downcity/type";
 import type { SessionUserMessagePart } from "@downcity/type";
 import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
@@ -17,21 +17,22 @@ import {
 
 /** 把 Downcity Session User parts 归一为 canonical User parts。 */
 export function normalize_session_user_parts(
-  parts: SessionPromptPart[] | null | undefined,
+  parts: SessionUserContent[] | 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}`,
+        sequence: index + 1,
         type: "text",
         text: part.text,
-        state: "done",
       }];
     }
     if (part.type === "context") {
       return [{
         part_id: `user-context:${index + 1}`,
+        sequence: index + 1,
         type: "context",
         tag: normalize_session_context_tag(part.tag),
         context: normalize_session_context_content(part.context),
@@ -40,6 +41,7 @@ export function normalize_session_user_parts(
     if (part.type === "file") {
       return [{
         part_id: `user-file:${index + 1}`,
+        sequence: index + 1,
         type: "file",
         url: part.url,
         media_type: part.media_type,
@@ -48,6 +50,7 @@ export function normalize_session_user_parts(
     }
     return [{
       part_id: `user-data:${index + 1}`,
+      sequence: index + 1,
       type: "data",
       data_type: part.data_type,
       data: to_session_json_value(part.data),
@@ -60,8 +63,8 @@ export function normalize_session_user_parts(
 export function normalize_canonical_session_user_parts(
   parts: readonly SessionUserMessagePart[],
 ): SessionUserMessagePart[] {
-  return parts.map((part) => {
-    const canonical = structuredClone(part);
+  return parts.map((part, index) => {
+    const canonical = { ...structuredClone(part), sequence: index + 1 };
     if (canonical.type !== "context") return canonical;
     return {
       ...canonical,
@@ -73,7 +76,7 @@ export function normalize_canonical_session_user_parts(
 
 /** 判断 Assistant 结果中是否包含可持久化内容。 */
 export function has_assistant_result_content(
-  parts: readonly SessionAssistantResultPart[],
+  parts: readonly SessionAgentContent[],
 ): boolean {
   return parts.some((part) => {
     if (part.type === "text") return Boolean(part.text.trim());